> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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 grant）
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/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/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 群组名称完全匹配。