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

# MastraAuthWorkos 类

`MastraAuthWorkos` 类使用 WorkOS 为 Mastra 提供身份验证。它通过 WorkOS access token 验证传入请求，并使用 `auth` 选项与 Mastra server 集成。

## 使用示例

```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 key，用于向 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 redirect URI。使用内置 WorkOS 登录流程时请设置此项。 (Default: `process.env.WORKOS_REDIRECT_URI`)

**fetchMemberships** (`boolean`): 在身份验证期间加载组织成员关系。使用 MastraFGAWorkos 时请将其设为 true，以便 FGA 检查解析正确的组织成员关系 ID。 (Default: `false`)

**trustJwtClaims** (`boolean`): 信任已验证的 bearer token claim，以便即使 workos.userManagement.getUser() 不适用也能构造 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 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。

## 默认授权行为

默认情况下，只要解析后的用户对象同时包含 `id` 和 `workosId`，`MastraAuthWorkos` 就会授权该已验证的 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 也可以为 service principal 验证已确认的 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`（issuer）、`exp`（过期时间），以及 `org_id`、`role` 和 `roles` 等 WorkOS 特定 claim。

## 相关内容

[MastraAuthWorkos 类](https://mastra.zisheng.pro/docs/server/auth/workos)