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 key。此 key 用於向 WorkOS API 進行身分驗證，以驗證使用者及管理組織。

clientId?:

string

= process.env.WORKOS_CLIENT_ID

你的 WorkOS Client ID。在用 authorization code 交換 access token 時，此值用於識別你的應用程式。

name?:

string

= "workos"

身分驗證 Provider 執行個體的自訂名稱。

redirectUri?:

string

= process.env.WORKOS_REDIRECT_URI

WorkOS AuthKit 使用的 OAuth redirect URI。使用內建的 WorkOS 登入流程時，請設定此值。

fetchMemberships?:

boolean

= false

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

trustJwtClaims?:

boolean

= false

信任已驗證的 bearer token claim，以便即使 workos.userManagement.getUser() 不適用，仍能建立 WorkOSUser。此選項適用於由 WorkOS 自訂 JWT template 支援的服務帳戶或機器對機器 token。

jwtClaims?:

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

將已驗證的 bearer JWT claim 對應至已通過身分驗證的 WorkOSUser。適用於包含 organizationMembershipId 或其他 FGA 特定 claim 的自訂 JWT template。

環境變數

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

WORKOS_API_KEY?:

string

你的 WorkOS API key。可在 WorkOS Dashboard 的 API Keys 中找到。

WORKOS_CLIENT_ID?:

string

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

WORKOS_REDIRECT_URI?:

string

使用內建 session 流程時，WorkOS AuthKit 所使用的 OAuth redirect 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 template 包含自訂 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 特定中繼資料。WorkOS 也允許管理員設定自訂 JWT template，因此確切結構可能因設定而異。以下範例顯示由 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 template 中設定的自訂 claim。標準 JWT claim 包括 sub（使用者 ID）、iss（issuer）、exp（到期時間），以及 org_id、role 和 roles 等 WorkOS 特定 claim。

相關內容

MastraAuthWorkos 類別