> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# Okta

`@mastra/auth-okta` 套件使用 Okta 為 Mastra 提供驗證與角色式存取控制。它支援使用加密工作階段 Cookie 的 OAuth 2.0 / OIDC 登入流程，並將 Okta 群組對應至 Mastra 權限。

## 先決條件

本指南使用 Okta 驗證。請務必：

1. 在 [okta.com](https://www.okta.com/) 建立 Okta 帳戶
2. 在 Okta Admin Console 中設定 OAuth 應用程式（Web 應用程式、Authorization Code 授權）
3. 將重新導向 URI 加入應用程式的登入重新導向 URI
4. 建立 API 權杖（RBAC 必須使用）

請確認已設定環境變數。

```env
OKTA_DOMAIN=dev-123456.okta.com
OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret
OKTA_REDIRECT_URI=http://localhost:4111/api/auth/callback
OKTA_COOKIE_PASSWORD=a-random-string-at-least-32-characters-long
OKTA_API_TOKEN=your-api-token
```

> **備註:** `OKTA_COOKIE_PASSWORD` 會加密工作階段 Cookie。如果省略，系統會使用無法在伺服器重新啟動後保留的自動產生值。請在正式環境中明確設定。
>
> 只有在使用 `MastraRBACOkta` 將 Okta 群組對應至權限時，才需要 `OKTA_API_TOKEN`。

## 安裝

**npm**:

```bash
npm install @mastra/auth-okta
```

**pnpm**:

```bash
pnpm add @mastra/auth-okta
```

**Yarn**:

```bash
yarn add @mastra/auth-okta
```

**Bun**:

```bash
bun add @mastra/auth-okta
```

## 使用範例

### 使用環境變數的基本用法

設定上述環境變數後，所有建構函式參數皆為選用：

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthOkta } from '@mastra/auth-okta'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta(),
  },
})
```

### 搭配 RBAC 的驗證

加入 `MastraRBACOkta`，將 Okta 群組對應至 Mastra 權限：

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthOkta, MastraRBACOkta } from '@mastra/auth-okta'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta(),
    rbac: new MastraRBACOkta({
      roleMapping: {
        Admin: ['*'],
        Engineering: ['agents:*', 'workflows:*', 'tools:*'],
        Viewer: ['agents:read', 'workflows:read'],
        _default: [], // users with unmapped groups get no permissions
      },
    }),
  },
})
```

### 跨 Provider 用法

使用其他驗證 Provider（Auth0、Clerk 等）登入，並使用 Okta 處理 RBAC。請傳入 `getUserId` 函式，從其他 Provider 的使用者物件解析 Okta 使用者 ID：

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthAuth0 } from '@mastra/auth-auth0'
import { MastraRBACOkta } from '@mastra/auth-okta'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthAuth0(),
    rbac: new MastraRBACOkta({
      getUserId: user => user.metadata?.oktaUserId || user.email,
      roleMapping: {
        Engineering: ['agents:*', 'workflows:*'],
        Admin: ['*'],
        _default: [],
      },
    }),
  },
})
```

> **備註:** 若要連結不同 Provider 的使用者，請將 Okta 使用者 ID 儲存在其他 Provider 的使用者中繼資料中。Mastra 會使用此 ID 從 Okta 取得群組。

請參閱 [MastraAuthOkta](https://mastra.zisheng.pro/zh-TW/reference/auth/okta)，瞭解所有可用的設定選項。

## 角色對應

`roleMapping` 選項會將 Okta 群組名稱對應至 Mastra 權限字串陣列。權限採用 `resource:action` 模式並支援萬用字元：

```typescript
const rbac = new MastraRBACOkta({
  roleMapping: {
    // full access to everything
    Admin: ['*'],

    // full access to agents and workflows
    Engineering: ['agents:*', 'workflows:*'],

    // read-only access
    Viewer: ['agents:read', 'workflows:read'],

    // users whose groups don't match any key above
    _default: [],
  },
})
```

`_default` 鍵會將權限指派給 Okta 群組不符合任何其他鍵的使用者。

## 用戶端設定

啟用驗證後，向 Mastra 路由發出的請求必須通過驗證。`MastraAuthOkta` 使用 SSO，因此使用者會透過 Okta 託管的登入頁面進行驗證。登入後，系統會自動設定加密的工作階段 Cookie。

### Cookie 工作階段（建議）

若為跨來源請求（例如在 `:3000` 執行的前端呼叫位於 `:4111` 的 Mastra），請在 Mastra 伺服器上啟用 CORS 憑證：

```typescript
export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta(),
    cors: {
      origin: 'http://localhost:3000',
      credentials: true,
    },
  },
})
```

設定用戶端以包含憑證：

```typescript
import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  credentials: 'include',
})
```

### Bearer 權杖

你也可以將 Okta 存取權杖當作 Bearer 權杖傳送。系統會透過 Okta 的 JWKS 端點驗證權杖：

```typescript
import { MastraClient } from '@mastra/client-js'

export const createMastraClient = (accessToken: string) => {
  return new MastraClient({
    baseUrl: 'http://localhost:4111',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  })
}
```

請參閱 [Mastra Client SDK](https://mastra.zisheng.pro/zh-TW/docs/server/mastra-client)，瞭解更多設定選項。

### 發出已驗證的請求

**MastraClient**:

```typescript
import { mastraClient } from '../lib/mastra-client'

const agent = mastraClient.getAgent('weatherAgent')
const response = await agent.generate('Weather in London')
console.log(response)
```

**cURL**:

```bash
curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-okta-access-token>" \
  -d '{
    "messages": "Weather in London"
  }'
```

## 疑難排解

- **每個請求都傳回 401**：確認 Okta 網域、用戶端 ID 及用戶端密鑰皆正確。檢查 Okta 應用程式中的重新導向 URI 是否符合 `OKTA_REDIRECT_URI`。
- **跨來源時未傳送 Cookie**：在 `MastraClient` 中設定 `credentials: "include"`，並以你的前端來源及 `credentials: true` 設定 `server.cors`。
- **重新啟動後工作階段遺失**：將 `OKTA_COOKIE_PASSWORD` 設為固定值（至少 32 個字元）。如果未設定，系統會使用每次重新啟動時都會變更的自動產生金鑰。
- **RBAC 傳回空白權限**：確認已設定 `OKTA_API_TOKEN`，且該權杖具備列出使用者群組的權限。檢查 `roleMapping` 中的群組名稱是否與 Okta 群組名稱完全相符。