跳至主要內容

MastraAuthOkta 與 MastraRBACOkta 類別

MastraAuthOkta 類別
「MastraAuthOkta 類別」的直接連結

MastraAuthOkta 類別使用 Okta 為 Mastra 提供身分驗證。它會實作採用加密 session 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）。用於建立 issuer URL 和 API endpoint。

clientId?:

string
= process.env.OKTA_CLIENT_ID
來自你的 Okta 應用程式的 OAuth client ID。

clientSecret?:

string
= process.env.OKTA_CLIENT_SECRET
OAuth client secret。SSO authorization code 流程必須提供此值。

issuer?:

string
= `https://{domain}/oauth2/default`
Token issuer URL。若使用自訂 authorization server，請覆寫此值。

redirectUri?:

string
= process.env.OKTA_REDIRECT_URI
SSO callback 的 OAuth redirect URI。必須與 Okta 應用程式中設定的 redirect 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
Session cookie 設定。
OktaSessionOptions

cookieName?:

string
Session cookie 的名稱。

cookieMaxAge?:

number
Cookie 的最長有效時間，以秒為單位。

cookiePassword?:

string
用於加密 session cookie 的密碼。長度必須至少為 32 個字元。若未設定，將使用自動產生的值，但此值不會在重新啟動後保留。

secureCookies?:

boolean
在 session cookie 上設定 Secure flag。

name?:

string
= 'okta'
身分驗證 Provider 執行個體的自訂名稱。

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

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

OKTA_DOMAIN:

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

OKTA_CLIENT_ID:

string
來自你的 Okta 應用程式的 OAuth client ID。

OKTA_CLIENT_SECRET:

string
來自你的 Okta 應用程式的 OAuth client secret。

OKTA_ISSUER?:

string
Token issuer URL。若未設定，預設為 https://{domain}/oauth2/default。

OKTA_REDIRECT_URI:

string
SSO callback 的 OAuth redirect URI。

OKTA_COOKIE_PASSWORD?:

string
用於加密 session cookie 的密碼。長度必須至少為 32 個字元。

OKTA_API_TOKEN?:

string
用於使用者查詢與 RBAC 群組解析的 Okta API token。

身分驗證流程
「身分驗證流程」的直接連結

MastraAuthOkta 會依下列順序驗證要求：

  1. Session cookie：讀取並解密已加密的 session cookie。如果 session 有效且未過期，使用者即通過身分驗證。
  2. JWT 備援方式：如果沒有 session cookie，則會透過 Okta 的 JWKS endpoint 驗證 Authorization header token。

身分驗證後，authorizeUser 會檢查使用者是否具有有效的 oktaId。若要實作其他邏輯，請提供自訂的 authorizeUser 函式。

OktaUser 型別
「oktauser-type」的直接連結

OktaUser 型別會以 Okta 特定欄位擴充基礎 EEUser interface：

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 需要有效的 Enterprise Edition 授權。開發環境中不需授權即可運作，因此你可以在本機試用；正式環境則需要授權。詳情請聯絡業務。

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

將 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 權限字串的 array。使用 '_default' 為不符合任何群組的使用者指派權限。支援 '*'（完整存取權）和 'agents:*'（所有 Agent 操作）等萬用字元。

domain?:

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

apiToken?:

string
= process.env.OKTA_API_TOKEN
Management SDK 的 Okta API token。從 Okta API 擷取使用者群組時必須提供此值。

getUserId?:

(user: unknown) => string | undefined
從使用者物件擷取 Okta 使用者 ID。將 Okta RBAC 與其他身分驗證 Provider 搭配使用時，請使用此項目。若未提供，會改用使用者物件上的 oktaId 或 id。

cache?:

PermissionCacheOptions
設定群組查詢的 LRU cache。
PermissionCacheOptions

maxSize?:

number
可快取的使用者數量上限。

ttlMs?:

number
存留時間，以毫秒為單位。
On this page