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.

先决条件

🌐 Prerequisites

此示例使用 WorkOS 认证。请确保：

🌐 This example uses WorkOS authentication. Make sure to:

1. 在 workos.com 创建一个 WorkOS 账户
2. 在你的 WorkOS 仪表板中设置应用
3. 配置你的重定向 URI 和允许的来源
4. 建立组织并根据需要配置用户角色

.env

WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...

note

你可以在 WorkOS 控制面板的“API 密钥”和“应用”下分别找到你的 API 密钥和客户端 ID。

🌐 You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.

有关详细的设置说明，请参阅你特定平台的 WorkOS 文档。

🌐 For detailed setup instructions, refer to the WorkOS documentation for your specific platform.

安装

🌐 Installation

在使用 MastraAuthWorkos 类之前，你必须先安装 @mastra/auth-workos 包。

🌐 Before you can use the MastraAuthWorkos class you have to install the @mastra/auth-workos package.

npm install @mastra/auth-workos@latest

用法示例

🌐 Usage examples

使用环境变量的基本用法

🌐 Basic usage with environment variables

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { MastraAuthWorkos } from "@mastra/auth-workos";

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos(),
  },
});

自定义配置

🌐 Custom configuration

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,
    }),
  },
});

配置

🌐 Configuration

用户授权

🌐 User Authorization

默认情况下，MastraAuthWorkos 会检查经过身份验证的用户在其任何组织成员资格中是否具有“管理员”角色。授权流程如下：

🌐 By default, MastraAuthWorkos checks whether the authenticated user has an 'admin' role in any of their organization memberships. The authorization process:

1. 使用用户 ID 检索用户的组织成员身份
2. 从其成员资格中提取所有角色
3. 检查是否有角色的别名为 'admin'
4. 仅当用户在至少一个组织中具有管理员角色时才授予访问权限

要自定义用户权限，请提供一个自定义的 authorizeUser 函数：

🌐 To customize user authorization, provide a custom authorizeUser function:

src/mastra/auth.ts

import { MastraAuthWorkos } from "@mastra/auth-workos";

const workosAuth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  authorizeUser: async (user) => {
    return !!user;
  },
});

info

访问 MastraAuthWorkos 查看所有可用的配置选项。

🌐 Visit MastraAuthWorkos for all available configuration options.

客户端设置

🌐 Client-side setup

在使用 WorkOS 认证时，你需要实现 WorkOS 的认证流程，将授权代码兑换为访问令牌，然后在你的 Mastra 请求中使用该令牌。

🌐 When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.

安装 WorkOS SDK

🌐 Installing WorkOS SDK

首先，在你的应用中安装 WorkOS SDK：

🌐 First, install the WorkOS SDK in your application:

npm install @workos-inc/node

将代码兑换为访问令牌

🌐 Exchanging code for access token

用户完成 WorkOS 认证流程并携带授权代码返回后，将其交换为访问令牌：

🌐 After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:

lib/auth.ts

import { WorkOS } from "@workos-inc/node";

const workos = new WorkOS(process.env.WORKOS_API_KEY);

export const authenticateWithWorkos = async (
  code: string,
  clientId: string,
) => {
  const authenticationResponse =
    await workos.userManagement.authenticateWithCode({
      code,
      clientId,
    });

  return authenticationResponse.accessToken;
};

note

有关更多身份验证方法和配置选项，请参考 WorkOS 用户管理文档。

🌐 Refer to the WorkOS User Management documentation for more authentication methods and configuration options.

配置 MastraClient

🌐 Configuring MastraClient

当启用 auth 时，所有使用 MastraClient 发出的请求必须在 Authorization 请求头中包含有效的 WorkOS 访问令牌：

🌐 When auth is enabled, all requests made with MastraClient must include a valid WorkOS access token in the Authorization header:

lib/mastra/mastra-client.ts

import { MastraClient } from "@mastra/client-js";

export const createMastraClient = (accessToken: string) => {
  return new MastraClient({
    baseUrl: "https://<mastra-api-url>",
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

info

访问令牌在 Authorization 头中必须以 Bearer 为前缀。

🌐 The access token must be prefixed with Bearer in the Authorization header.

访问 Mastra Client SDK 以获取更多配置选项。

🌐 Visit Mastra Client SDK for more configuration options.

进行身份验证的请求

🌐 Making authenticated requests

一旦使用 WorkOS 访问令牌配置了 MastraClient，你就可以发送经过身份验证的请求：

🌐 Once MastraClient is configured with the WorkOS access token, you can send authenticated requests:

React

src/api/agents.ts

import { WorkOS } from '@workos-inc/node';
import { MastraClient } from '@mastra/client-js';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

export const callMastraWithWorkos = async (code: string, clientId: string) => {
  const authenticationResponse = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  });

  const token = authenticationResponse.accessToken;

  const mastra = new MastraClient({
    baseUrl: "http://localhost:4111",
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });

  const weatherAgent = mastra.getAgent("weatherAgent");
  const response = await weatherAgent.generate("What's the weather like in Nairobi");

  return response.text;
};

cURL

curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-workos-access-token>" \
  -d '{
    "messages": "Weather in London"
  }'