跳至主要內容

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 授權）
  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 install @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 的驗證
「搭配 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 用法」的直接連結

使用其他驗證 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。

若為跨來源請求（例如在 :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 權杖
「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，瞭解更多設定選項。

發出已驗證的請求
「發出已驗證的請求」的直接連結

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)

疑難排解
「疑難排解」的直接連結

  • 每個請求都傳回 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 群組名稱完全相符。
On this page