MastraAuthWorkos 類別

MastraAuthWorkos 類別使用 WorkOS 為 Mastra 提供身份驗證。它使用 WorkOS access token 驗證傳入的請求，並透過 auth 選項與 Mastra 伺服器整合。

使用範例

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthWorkos } from '@mastra/auth-workos'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos({
      apiKey: process.env.WORKOS_API_KEY,
      clientId: process.env.WORKOS_CLIENT_ID,
    }),
  },
})

備註

如果已設定所需的環境變數（WORKOS_API_KEY 和 WORKOS_CLIENT_ID），便可省略建構函數參數。在這種情況下，使用不帶任何引數的 new MastraAuthWorkos()。

建構函數參數

apiKey?:

string

= process.env.WORKOS_API_KEY

你的 WorkOS API 金鑰。這用於向 WorkOS API 進行身份驗證，以驗證用戶及管理機構。

clientId?:

string

= process.env.WORKOS_CLIENT_ID

你的 WorkOS Client ID。使用授權碼交換 access token 時，這會識別你的應用程式。

name?:

string

= "workos"

身份驗證 Provider 實例的自訂名稱。

redirectUri?:

string

= process.env.WORKOS_REDIRECT_URI

WorkOS AuthKit 使用的 OAuth 重新導向 URI。使用內置 WorkOS 登入流程時，請設定此項。

fetchMemberships?:

boolean

= false

在身份驗證期間載入機構成員資格。使用 MastraFGAWorkos 時，請將此項設為 true，讓 FGA 檢查可以解析正確的機構成員資格 ID。

trustJwtClaims?:

boolean

= false

即使 workos.userManagement.getUser() 不適用，仍充分信任已驗證的 bearer token claim，以建立 WorkOSUser。這適用於由 WorkOS 自訂 JWT 範本支援的服務帳戶或機器對機器 token。

jwtClaims?:

{ userId?: string; workosId?: string; email?: string; name?: string; organizationId?: string; organizationMembershipId?: string }

將已驗證的 bearer JWT claim 映射至已通過身份驗證的 WorkOSUser。適用於包含 organizationMembershipId 或其他 FGA 特定 claim 的自訂 JWT 範本。

環境變數

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

WORKOS_API_KEY?:

string

你的 WorkOS API 金鑰。可在 WorkOS Dashboard 的 API Keys 下找到。

WORKOS_CLIENT_ID?:

string

你的 WorkOS Client ID。可在 WorkOS Dashboard 的 Applications 下找到。

WORKOS_REDIRECT_URI?:

string

使用內置、基於 session 的流程時，WorkOS AuthKit 所使用的 OAuth 重新導向 URI。

預設授權行為

預設情況下，MastraAuthWorkos 會授權任何已通過身份驗證，且所解析用戶物件同時包含 id 和 workosId 的 WorkOS 用戶。

1. Token 驗證：使用 WorkOS 驗證 access token，確保它有效且尚未過期
2. 擷取用戶：從已驗證的 token 擷取用戶資料
3. 授權決定：如果解析出的用戶包含所需識別碼，便授予存取權

MastraAuthWorkos 預設用作身份驗證 Provider，而非角色閘門。

載入 FGA 成員資格

使用 MastraFGAWorkos 時，請設定 fetchMemberships: true。這會在身份驗證期間載入用戶的 WorkOS 機構成員資格，讓 FGA 檢查可以解析正確的機構成員資格 ID。

當 fetchMemberships 為 false 時，Mastra 會在每個已通過身份驗證的請求中略過額外的 WorkOS listOrganizationMemberships() 呼叫。

服務 token 和 JWT claim

如果你的 WorkOS JWT 範本包含自訂 claim，可以將它們直接映射至已通過身份驗證的 WorkOSUser。

src/mastra/auth.ts

import { MastraAuthWorkos } from '@mastra/auth-workos'

const auth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  redirectUri: process.env.WORKOS_REDIRECT_URI,
  trustJwtClaims: true,
  jwtClaims: {
    organizationId: 'org_id',
    organizationMembershipId: 'urn:mastra:organization_membership_id',
  },
})

啟用 trustJwtClaims 後，即使 getUser() 並非合適的查詢途徑，Mastra 仍可驗證服務主體的已驗證 bearer token。對於機器對機器流程，這是將預先解析的 organizationMembershipId 值傳入 FGA 檢查的首選方式。

自訂授權

如果需要更嚴格的授權，請繼承 MastraAuthWorkos 並覆寫 authorizeUser()：

src/mastra/auth.ts

import { MastraAuthWorkos } from '@mastra/auth-workos'
import type { HonoRequest } from 'hono'

class AdminOnlyWorkosAuth extends MastraAuthWorkos {
  async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
    return user?.metadata?.role === 'admin'
  }
}

WorkOS 用戶類型

authorizeUser() 及其他 WorkOS 身份驗證 hook 中可用的 WorkOSUser 類型，包含 Mastra 的標準化用戶欄位及 WorkOS 特定 metadata。WorkOS 也允許管理員設定自訂 JWT 範本，因此實際結構可能因你的設定而異。以下範例顯示由 WorkOS 支援的用戶物件可能呈現的形式：

{
  'urn:myapp:full_name': 'John Doe',
  'urn:myapp:email': 'john.doe@example.com',
  'urn:myapp:organization_tier': 'bronze',
  'urn:myapp:user_language': 'en',
  'urn:myapp:organization_domain': 'example.com',
  iss: 'https://api.workos.com/user_management/client_01ABC123DEF456GHI789JKL012',
  sub: 'user_01XYZ789ABC123DEF456GHI012',
  sid: 'session_01PQR456STU789VWX012YZA345',
  jti: '01MNO678PQR901STU234VWX567',
  org_id: 'org_01DEF234GHI567JKL890MNO123',
  role: 'member',
  roles: [ 'member' ],
  permissions: [],
  exp: 1758290589,
  iat: 1758290289
}

帶有 urn:myapp: 前綴的屬性是在 WorkOS JWT 範本中設定的自訂 claim。標準 JWT claim 包括 sub（用戶 ID）、iss（簽發者）、exp（到期時間），以及 org_id、role 和 roles 等 WorkOS 特定 claim。

相關內容

MastraAuthWorkos 類別