> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# MastraAuthWorkos 類別

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

## 使用範例

```typescript
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`): 你的 WorkOS API 金鑰。這用於向 WorkOS API 進行身份驗證，以驗證用戶及管理機構。 (Default: `process.env.WORKOS_API_KEY`)

**clientId** (`string`): 你的 WorkOS Client ID。使用授權碼交換 access token 時，這會識別你的應用程式。 (Default: `process.env.WORKOS_CLIENT_ID`)

**name** (`string`): 身份驗證 Provider 實例的自訂名稱。 (Default: `"workos"`)

**redirectUri** (`string`): WorkOS AuthKit 使用的 OAuth 重新導向 URI。使用內置 WorkOS 登入流程時，請設定此項。 (Default: `process.env.WORKOS_REDIRECT_URI`)

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

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

**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`。

```typescript
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()`：

```typescript
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 支援的用戶物件可能呈現的形式：

```javascript
{
  '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 類別](https://mastra.zisheng.pro/zh-HK/docs/server/auth/workos)