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

# MastraAuthOkta 與 MastraRBACOkta 類別

## MastraAuthOkta 類別

`MastraAuthOkta` 類別使用 Okta 為 Mastra 提供身分驗證。它會實作採用加密 session cookie 的 OAuth 2.0 / OIDC 登入流程，並透過 `auth` 選項與 Mastra 伺服器整合。

### 使用範例

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

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta({
      domain: process.env.OKTA_DOMAIN,
      clientId: process.env.OKTA_CLIENT_ID,
      clientSecret: process.env.OKTA_CLIENT_SECRET,
      redirectUri: process.env.OKTA_REDIRECT_URI,
    }),
  },
})
```

> **備註:** 若已設定必要的環境變數，可以省略建構函式參數。在這種情況下，請使用不帶任何引數的 `new MastraAuthOkta()`。

### 建構函式參數

**domain** (`string`): 你的 Okta 網域（例如 dev-123456.okta.com）。用於建立 issuer URL 和 API endpoint。 (Default: `process.env.OKTA_DOMAIN`)

**clientId** (`string`): 來自你的 Okta 應用程式的 OAuth client ID。 (Default: `process.env.OKTA_CLIENT_ID`)

**clientSecret** (`string`): OAuth client secret。SSO authorization code 流程必須提供此值。 (Default: `process.env.OKTA_CLIENT_SECRET`)

**issuer** (`string`): Token issuer URL。若使用自訂 authorization server，請覆寫此值。 (Default: `` `https://{domain}/oauth2/default` ``)

**redirectUri** (`string`): SSO callback 的 OAuth redirect URI。必須與 Okta 應用程式中設定的 redirect URI 相符。 (Default: `process.env.OKTA_REDIRECT_URI`)

**scopes** (`string[]`): 登入流程期間要要求的 OAuth scope。 (Default: `['openid', 'profile', 'email', 'groups']`)

**apiToken** (`string`): 用於透過 Users API 查詢使用者的 Okta API token。若要讓 getUser() 依 ID 傳回使用者資料，必須提供此值。 (Default: `process.env.OKTA_API_TOKEN`)

**session** (`OktaSessionOptions`): Session cookie 設定。

**session.cookieName** (`string`): Session cookie 的名稱。

**session.cookieMaxAge** (`number`): Cookie 的最長有效時間，以秒為單位。

**session.cookiePassword** (`string`): 用於加密 session cookie 的密碼。長度必須至少為 32 個字元。若未設定，將使用自動產生的值，但此值不會在重新啟動後保留。

**session.secureCookies** (`boolean`): 在 session cookie 上設定 Secure flag。

**name** (`string`): 身分驗證 Provider 執行個體的自訂名稱。 (Default: `'okta'`)

### 環境變數

未提供建構函式選項時，會自動使用以下環境變數：

**OKTA\_DOMAIN** (`string`): 你的 Okta 網域（例如 dev-123456.okta.com）。可在 Okta 管理主控台中找到。

**OKTA\_CLIENT\_ID** (`string`): 來自你的 Okta 應用程式的 OAuth client ID。

**OKTA\_CLIENT\_SECRET** (`string`): 來自你的 Okta 應用程式的 OAuth client secret。

**OKTA\_ISSUER** (`string`): Token issuer URL。若未設定，預設為 https\://{domain}/oauth2/default。

**OKTA\_REDIRECT\_URI** (`string`): SSO callback 的 OAuth redirect URI。

**OKTA\_COOKIE\_PASSWORD** (`string`): 用於加密 session cookie 的密碼。長度必須至少為 32 個字元。

**OKTA\_API\_TOKEN** (`string`): 用於使用者查詢與 RBAC 群組解析的 Okta API token。

### 身分驗證流程

`MastraAuthOkta` 會依下列順序驗證要求：

1. **Session cookie**：讀取並解密已加密的 session cookie。如果 session 有效且未過期，使用者即通過身分驗證。
2. **JWT 備援方式**：如果沒有 session cookie，則會透過 Okta 的 JWKS endpoint 驗證 `Authorization` header token。

身分驗證後，`authorizeUser` 會檢查使用者是否具有有效的 `oktaId`。若要實作其他邏輯，請提供自訂的 `authorizeUser` 函式。

### `OktaUser` 型別

`OktaUser` 型別會以 Okta 特定欄位擴充基礎 `EEUser` interface：

**id** (`string`): 使用者識別碼（對應至 sub claim）。

**oktaId** (`string`): Okta 使用者 ID（與 id 相同）。

**email** (`string`): 使用者電子郵件地址。

**name** (`string`): 從 token claim 建立的使用者顯示名稱。

**avatarUrl** (`string`): 使用者個人資料圖片的 URL。

**groups** (`string[]`): 使用者所屬的 Okta 群組，從 groups claim 填入。

## MastraRBACOkta 類別

`MastraRBACOkta` 類別會將 Okta 群組對應至 Mastra 權限。它會從 Okta API 擷取使用者群組，並依可設定的角色對應解析群組。請將其與 `MastraAuthOkta` 或任何其他身分驗證 Provider 搭配使用。

> **備註:** RBAC 需要有效的 Enterprise Edition 授權。開發環境中不需授權即可運作，因此你可以在本機試用；正式環境則需要授權。詳情請[聯絡業務](https://mastra.ai/contact)。

### 使用範例

將 `MastraRBACOkta` 傳遞給 `rbac` 選項，即可搭配身分驗證 Provider 使用：

```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: [],
      },
    }),
  },
})
```

若要將 Okta RBAC 與其他身分驗證 Provider 搭配使用，請傳入 `getUserId` 函式，從其他 Provider 的使用者物件解析 Okta 使用者 ID：

```typescript
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: [],
      },
    }),
  },
})
```

### 建構函式參數

**roleMapping** (`RoleMapping`): 將 Okta 群組名稱對應至 Mastra 權限字串的 array。使用 '\_default' 為不符合任何群組的使用者指派權限。支援 '\*'（完整存取權）和 'agents:\*'（所有 Agent 操作）等萬用字元。

**domain** (`string`): 你的 Okta 網域。用於初始化 Okta management SDK。 (Default: `process.env.OKTA_DOMAIN`)

**apiToken** (`string`): Management SDK 的 Okta API token。從 Okta API 擷取使用者群組時必須提供此值。 (Default: `process.env.OKTA_API_TOKEN`)

**getUserId** (`(user: unknown) => string | undefined`): 從使用者物件擷取 Okta 使用者 ID。將 Okta RBAC 與其他身分驗證 Provider 搭配使用時，請使用此項目。若未提供，會改用使用者物件上的 oktaId 或 id。

**cache** (`PermissionCacheOptions`): 設定群組查詢的 LRU cache。

**cache.maxSize** (`number`): 可快取的使用者數量上限。

**cache.ttlMs** (`number`): 存留時間，以毫秒為單位。