Okta

@mastra/auth-okta 套件透過 Okta 為 Mastra 提供身份驗證和角色型存取控制。它支援使用加密工作階段 Cookie 的 OAuth 2.0 / OIDC 登入流程，並將 Okta 群組對應至 Mastra 權限。

先決條件

本指南使用 Okta 身份驗證。請確保你已：

1. 在 okta.com 建立 Okta 帳戶
2. 在 Okta Admin Console 設定 OAuth 應用程式（Web app、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 的使用者 metadata 中。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 key 會為 Okta 群組與其他任何 key 均不相符的使用者指派權限。

用戶端設定

啟用身份驗證後，向 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 個字元）。如未設定，系統會使用自動產生的 key，而該 key 每次重新啟動時都會變更。
• RBAC 傳回空白權限：確認已設定 OKTA_API_TOKEN，且該 API 金鑰具備列出使用者群組的權限。檢查 roleMapping 中的群組名稱與你的 Okta 群組名稱完全相符。