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

# MastraAuthOkta 及 MastraRBACOkta 類別

## MastraAuthOkta 類別

`MastraAuthOkta` 類別使用 Okta 為 Mastra 提供身份驗證。它實作採用加密工作階段 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）。用於建構簽發者 URL 及 API 端點。 (Default: `process.env.OKTA_DOMAIN`)

**clientId** (`string`): 你的 Okta 應用程式所提供的 OAuth 客戶端 ID。 (Default: `process.env.OKTA_CLIENT_ID`)

**clientSecret** (`string`): OAuth 客戶端密鑰。SSO 授權碼流程必須提供此項。 (Default: `process.env.OKTA_CLIENT_SECRET`)

**issuer** (`string`): Token 簽發者 URL。如使用自訂授權伺服器，請覆寫此項。 (Default: `` `https://{domain}/oauth2/default` ``)

**redirectUri** (`string`): SSO 回呼的 OAuth 重新導向 URI。必須與你在 Okta 應用程式中設定的重新導向 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`): 工作階段 cookie 設定。

**session.cookieName** (`string`): 工作階段 cookie 的名稱。

**session.cookieMaxAge** (`number`): Cookie 的最長有效時間（秒）。

**session.cookiePassword** (`string`): 用於加密工作階段 cookie 的密碼。必須至少有 32 個字元。如未設定，系統會使用自動產生的值，但該值在重新啟動後不會保留。

**session.secureCookies** (`boolean`): 在工作階段 cookie 上設定 Secure 標記。

**name** (`string`): 身份驗證 Provider 實例的自訂名稱。 (Default: `'okta'`)

### 環境變數

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

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

**OKTA\_CLIENT\_ID** (`string`): 你的 Okta 應用程式所提供的 OAuth 客戶端 ID。

**OKTA\_CLIENT\_SECRET** (`string`): 你的 Okta 應用程式所提供的 OAuth 客戶端密鑰。

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

**OKTA\_REDIRECT\_URI** (`string`): SSO 回呼的 OAuth 重新導向 URI。

**OKTA\_COOKIE\_PASSWORD** (`string`): 用於加密工作階段 cookie 的密碼。必須至少有 32 個字元。

**OKTA\_API\_TOKEN** (`string`): 用於查找用戶及解析 RBAC 群組的 Okta API token。

### 身份驗證流程

`MastraAuthOkta` 會按以下順序驗證請求：

1. **工作階段 cookie**：讀取並解密已加密的工作階段 cookie。如工作階段有效且尚未過期，即會驗證用戶身份。
2. **JWT 後備方式**：如沒有工作階段 cookie，則使用 Okta 的 JWKS 端點驗證 `Authorization` 標頭中的 token。

身份驗證後，`authorizeUser` 會檢查用戶是否有有效的 `oktaId`。請提供自訂 `authorizeUser` 函數以實作額外邏輯。

### `OktaUser` 類型

`OktaUser` 類型以 Okta 專用欄位擴充基礎 `EEUser` 介面：

**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 需要有效的企業版授權。在開發環境中，即使沒有授權也能運作，讓你可以在本機試用；但在生產環境中則需要授權。詳情請[聯絡銷售團隊](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 權限字串陣列。使用 '\_default' 向不符合任何群組的用戶指派權限。支援 '\*'（完整存取權）及 'agents:\*'（所有 Agent 操作）等萬用字元。

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

**apiToken** (`string`): 管理 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.maxSize** (`number`): 要快取的用戶數目上限。

**cache.ttlMs** (`number`): 存留時間（毫秒）。