Okta

@mastra/auth-okta 包使用 Okta 为 Mastra 提供身份验证和基于角色的访问控制。它支持使用加密会话 Cookie 的 OAuth 2.0 / OIDC 登录流程，并将 Okta 群组映射到 Mastra 权限。

前置条件

本指南使用 Okta 身份验证。请确保：

1. 在 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

npm install @mastra/auth-okta

pnpm

pnpm add @mastra/auth-okta

Yarn

yarn add @mastra/auth-okta

Bun

bun add @mastra/auth-okta

用法示例

使用环境变量的基本用法

设置上述环境变量后，所有构造函数参数均为可选：

src/mastra/index.ts

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

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

使用 RBAC 进行身份验证

添加 MastraRBACOkta，将 Okta 群组映射到 Mastra 权限：

src/mastra/index.ts

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：

src/mastra/index.ts

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。

角色映射

roleMapping 选项将 Okta 群组名称映射到 Mastra 权限字符串数组。权限遵循 resource:action 模式并支持通配符：

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 凭据：

src/mastra/index.ts

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

配置客户端以包含凭据：

lib/mastra-client.ts

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

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

Bearer 令牌

也可以将 Okta 访问令牌作为 Bearer 令牌传递。系统会根据 Okta 的 JWKS 端点验证该令牌：

lib/mastra-client.ts

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。

发出经过身份验证的请求

MastraClient

src/api/agents.ts

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

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

cURL

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 群组名称完全匹配。