MastraAuthWorkos 类

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

使用示例

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，用于向 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 redirect URI。使用内置 WorkOS 登录流程时请设置此项。

fetchMemberships?:

boolean

= false

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

trustJwtClaims?:

boolean

= false

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

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 也可以为 service principal 验证已确认的 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（issuer）、exp（过期时间），以及 org_id、role 和 roles 等 WorkOS 特定 claim。

相关内容

MastraAuthWorkos 类