Skip to main content

MastraAuthWorkos 类

🌐 MastraAuthWorkos Class

MastraAuthWorkos 类提供了使用 WorkOS 的 Mastra 身份验证。它使用 WorkOS 访问令牌验证传入请求，并通过 auth 选项与 Mastra 服务器集成。

🌐 The MastraAuthWorkos class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the auth option.

使用示例
Direct link to 使用示例

🌐 Usage example

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() 而无需任何参数。

构造函数参数
Direct link to 构造函数参数

🌐 Constructor parameters

apiKey?:

string
= process.env.WORKOS_API_KEY
Your WorkOS API key. This is used to authenticate with the WorkOS API for user verification and organization management.

clientId?:

string
= process.env.WORKOS_CLIENT_ID
Your WorkOS Client ID. This identifies your application when exchanging authorization codes for access tokens.

name?:

string
= "workos"
Custom name for the auth provider instance.

authorizeUser?:

(user: WorkosUser) => Promise<boolean> | boolean
Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks if the user has an 'admin' role in any organization membership.

环境变量
Direct link to 环境变量

🌐 Environment Variables

当没有提供构造函数选项时，会自动使用以下环境变量：

🌐 The following environment variables are automatically used when constructor options are not provided:

WORKOS_API_KEY?:

string
Your WorkOS API key. Can be found in your WorkOS Dashboard under API Keys.

WORKOS_CLIENT_ID?:

string
Your WorkOS Client ID. Can be found in your WorkOS Dashboard under Applications.

默认授权行为
Direct link to 默认授权行为

🌐 Default Authorization Behavior

默认情况下，MastraAuthWorkos 实现了基于角色的授权，用于检查管理员访问权限：

🌐 By default, MastraAuthWorkos implements role-based authorization that checks for admin access:

  1. 令牌验证：访问令牌会通过 WorkOS 进行验证，以确保其有效且未过期
  2. 用户检索：用户信息从已验证的令牌中提取
  3. 组织成员资格检查：系统查询 WorkOS 以获取与用户 ID 相关的所有组织成员资格
  4. 角色提取：收集用户所属组织中的所有角色
  5. 管理员检查：系统会检查是否有任何角色的别名为 'admin'
  6. 授权决定：只有当用户在至少一个组织中拥有管理员角色时，才授予访问权限

这意味着默认情况下，只有在至少一个组织中具有管理员权限的用户才被授权访问你的 Mastra 端点。

🌐 This means that by default, only users with admin privileges in at least one organization will be authorized to access your Mastra endpoints.

要实现自定义授权逻辑（例如，允许所有已认证用户、检查特定角色或实现自定义业务逻辑），请提供一个自定义的 authorizeUser 函数。

🌐 To implement custom authorization logic (e.g., allow all authenticated users, check for specific roles, or implement custom business logic), provide a custom authorizeUser function.

WorkOS 用户类型
Direct link to WorkOS 用户类型

🌐 WorkOS User Type

authorizeUser 函数中使用的 WorkosUser 类型对应于 WorkOS 返回的 JWT 令牌负载。WorkOS 允许管理员设置自定义 JWT 模板，因此具体结构可能会根据你的配置有所不同。以下是用户对象可能的示例:

🌐 The WorkosUser type used in the authorizeUser function corresponds to the JWT token payload returned by WorkOS. WorkOS allows administrators to set up custom JWT templates, so the exact structure may vary based on your configuration. Here's an example of what the user object might look like:

{
  '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 模板中配置的自定义声明。标准的 JWT 声明包括 sub（用户 ID）、iss（发行者）、exp（过期时间），以及 WorkOS 特有的声明，如 org_id、role 和 roles。

🌐 The properties with urn:myapp: prefixes are custom claims configured in your WorkOS JWT template. Standard JWT claims include sub (user ID), iss (issuer), exp (expiration), and WorkOS-specific claims like org_id, role, and roles.

🌐 Related

MastraAuthWorkos 类

目录