跳至主要內容

MastraAuthOkta 及 MastraRBACOkta 類別

MastraAuthOkta 類別
MastraAuthOkta 類別 的直接連結

MastraAuthOkta 類別使用 Okta 為 Mastra 提供身份驗證。它實作採用加密工作階段 cookie 的 OAuth 2.0 / OIDC 登入流程，並透過 auth 選項與 Mastra 伺服器整合。

使用範例
使用範例 的直接連結

src/mastra/index.ts
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
= process.env.OKTA_DOMAIN
你的 Okta 網域（例如 dev-123456.okta.com）。用於建構簽發者 URL 及 API 端點。

clientId?:

string
= process.env.OKTA_CLIENT_ID
你的 Okta 應用程式所提供的 OAuth 客戶端 ID。

clientSecret?:

string
= process.env.OKTA_CLIENT_SECRET
OAuth 客戶端密鑰。SSO 授權碼流程必須提供此項。

issuer?:

string
= `https://{domain}/oauth2/default`
Token 簽發者 URL。如使用自訂授權伺服器，請覆寫此項。

redirectUri?:

string
= process.env.OKTA_REDIRECT_URI
SSO 回呼的 OAuth 重新導向 URI。必須與你在 Okta 應用程式中設定的重新導向 URI 相符。

scopes?:

string[]
= ['openid', 'profile', 'email', 'groups']
登入流程期間要請求的 OAuth scope。

apiToken?:

string
= process.env.OKTA_API_TOKEN
透過 Users API 查找用戶所需的 Okta API token。getUser() 必須有此項，才能按 ID 傳回用戶資料。

session?:

OktaSessionOptions
工作階段 cookie 設定。
OktaSessionOptions

cookieName?:

string
工作階段 cookie 的名稱。

cookieMaxAge?:

number
Cookie 的最長有效時間（秒）。

cookiePassword?:

string
用於加密工作階段 cookie 的密碼。必須至少有 32 個字元。如未設定，系統會使用自動產生的值，但該值在重新啟動後不會保留。

secureCookies?:

boolean
在工作階段 cookie 上設定 Secure 標記。

name?:

string
= 'okta'
身份驗證 Provider 實例的自訂名稱。

環境變數
環境變數 的直接連結

如未提供建構函數選項，系統會自動使用以下環境變數：

OKTA_DOMAIN:

string
你的 Okta 網域（例如 dev-123456.okta.com）。可在 Okta 管理控制台中找到。

OKTA_CLIENT_ID:

string
你的 Okta 應用程式所提供的 OAuth 客戶端 ID。

OKTA_CLIENT_SECRET:

string
你的 Okta 應用程式所提供的 OAuth 客戶端密鑰。

OKTA_ISSUER?:

string
Token 簽發者 URL。如未設定，預設為 https://{domain}/oauth2/default。

OKTA_REDIRECT_URI:

string
SSO 回呼的 OAuth 重新導向 URI。

OKTA_COOKIE_PASSWORD?:

string
用於加密工作階段 cookie 的密碼。必須至少有 32 個字元。

OKTA_API_TOKEN?:

string
用於查找用戶及解析 RBAC 群組的 Okta API token。

身份驗證流程
身份驗證流程 的直接連結

MastraAuthOkta 會按以下順序驗證請求：

  1. 工作階段 cookie：讀取並解密已加密的工作階段 cookie。如工作階段有效且尚未過期，即會驗證用戶身份。
  2. JWT 後備方式：如沒有工作階段 cookie，則使用 Okta 的 JWKS 端點驗證 Authorization 標頭中的 token。

身份驗證後，authorizeUser 會檢查用戶是否有有效的 oktaId。請提供自訂 authorizeUser 函數以實作額外邏輯。

OktaUser 類型
oktauser-type 的直接連結

OktaUser 類型以 Okta 專用欄位擴充基礎 EEUser 介面：

id:

string
用戶識別碼（對應至 sub claim）。

oktaId:

string
Okta 用戶 ID（與 id 相同）。

email?:

string
用戶電郵地址。

name?:

string
從 token claim 建構的用戶顯示名稱。

avatarUrl?:

string
用戶個人資料圖片的 URL。

groups?:

string[]
用戶所屬的 Okta 群組，從 groups claim 填入。

MastraRBACOkta 類別
MastraRBACOkta 類別 的直接連結

MastraRBACOkta 類別會將 Okta 群組對應至 Mastra 權限。它會從 Okta API 擷取用戶群組，並根據可設定的角色對應解析這些群組。你可以將它與 MastraAuthOkta 或任何其他身份驗證 Provider 配合使用。

備註

RBAC 需要有效的企業版授權。在開發環境中，即使沒有授權也能運作，讓你可以在本機試用；但在生產環境中則需要授權。詳情請聯絡銷售團隊。

使用範例
使用範例 的直接連結

將 MastraRBACOkta 傳入 rbac 選項，即可與身份驗證 Provider 配合使用：

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: [],
      },
    }),
  },
})

如要將 Okta RBAC 與其他身份驗證 Provider 配合使用，請傳入 getUserId 函數，以從其他 Provider 的用戶物件解析 Okta 用戶 ID：

src/mastra/index.ts
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 群組名稱對應至 Mastra 權限字串陣列。使用 '_default' 向不符合任何群組的用戶指派權限。支援 '*'（完整存取權）及 'agents:*'（所有 Agent 操作）等萬用字元。

domain?:

string
= process.env.OKTA_DOMAIN
你的 Okta 網域。用於初始化 Okta 管理 SDK。

apiToken?:

string
= process.env.OKTA_API_TOKEN
管理 SDK 使用的 Okta API token。必須提供此項，才能從 Okta API 擷取用戶群組。

getUserId?:

(user: unknown) => string | undefined
從用戶物件擷取 Okta 用戶 ID。將 Okta RBAC 與其他身份驗證 Provider 結合使用時，請使用此項。如未提供，則後備使用用戶物件上的 oktaId 或 id。

cache?:

PermissionCacheOptions
設定用於群組查找的 LRU 快取。
PermissionCacheOptions

maxSize?:

number
要快取的用戶數目上限。

ttlMs?:

number
存留時間（毫秒）。
On this page