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

# MastraAuthOkta 和 MastraRBACOkta 类

## MastraAuthOkta 类

`MastraAuthOkta` 类使用 Okta 为 Mastra 提供身份验证。它实现使用加密 Session cookie 的 OAuth 2.0 / OIDC 登录流程，并使用 `auth` 选项与 Mastra server 集成。

### 使用示例

```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 标志。

**name** (`string`): Auth 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 group 解析的 Okta API token。

### 身份验证流程

`MastraAuthOkta` 按以下顺序对请求进行身份验证：

1. **Session cookie**：读取并解密已加密的 Session cookie。如果 Session 有效且未过期，则用户身份验证成功。
2. **JWT fallback**：如果不存在 Session cookie，则根据 Okta 的 JWKS endpoint 验证 `Authorization` header 中的 token。

身份验证完成后，`authorizeUser` 会检查用户是否具有有效的 `oktaId`。可以提供自定义 `authorizeUser` 函数来实现其他逻辑。

### `OktaUser` 类型

`OktaUser` 类型扩展了基础 `EEUser` interface，并增加 Okta 专用字段：

**id** (`string`): 用户标识符（映射到 sub claim）。

**oktaId** (`string`): Okta user ID（与 id 相同）。

**email** (`string`): 用户电子邮件地址。

**name** (`string`): 根据 token claim 构造的用户显示名称。

**avatarUrl** (`string`): 用户头像的 URL。

**groups** (`string[]`): 用户所属的 Okta group，由 groups claim 填充。

## MastraRBACOkta 类

`MastraRBACOkta` 类将 Okta group 映射到 Mastra permission。它从 Okta API 获取用户 group，并根据可配置的 role mapping 进行解析。可以将其与 `MastraAuthOkta` 或其他 Auth Provider 搭配使用。

> **备注:** RBAC 需要有效的 Enterprise Edition license。在开发环境中无需 license 即可运行，方便本地试用；生产环境则需要 license。有关详细信息，请[联系销售团队](https://mastra.ai/contact)。

### 使用示例

将 `MastraRBACOkta` 传给 `rbac` 选项，即可与 Auth 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 与其他 Auth Provider 搭配使用，请传入 `getUserId` 函数，从其他 Provider 的用户对象中解析 Okta user 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 group 名称映射到 Mastra permission 字符串数组。使用 '\_default' 为不匹配任何 group 的用户分配 permission。支持 '\*'（完全访问权限）和 'agents:\*'（所有 Agent 操作）等通配符。

**domain** (`string`): Okta 域，用于初始化 Okta management SDK。 (Default: `process.env.OKTA_DOMAIN`)

**apiToken** (`string`): Management SDK 使用的 Okta API token。从 Okta API 获取用户 group 时必需。 (Default: `process.env.OKTA_API_TOKEN`)

**getUserId** (`(user: unknown) => string | undefined`): 从用户对象中提取 Okta user ID。将 Okta RBAC 与其他 Auth Provider 组合使用时请提供此项。未提供时，会 fallback 到用户对象中的 oktaId 或 id。

**cache** (`PermissionCacheOptions`): 配置用于 group 查找的 LRU cache。

**cache.maxSize** (`number`): 可缓存的最大用户数。

**cache.ttlMs** (`number`): 有效期，单位为毫秒。