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

# Studio 身份验证

在 Mastra Server 上配置[身份验证](https://mastra.zisheng.pro/docs/server/auth)后，Studio 会自动显示登录页面并强制执行访问控制。一项配置即可同时保护 Studio UI 和 API 路由。

如果未配置身份验证，Studio 和所有 API 路由都可公开访问。

## 何时使用 Studio Auth

- 多名团队成员需要通过共享的 Studio 部署与 Agent、Workflow 和 Tool 交互。
- 需要通过权限限制谁能执行 Agent、编辑 Workflow 或删除数据集。
- 应通过登录页面（SSO、邮箱/密码或二者兼有）限制对 Studio 部署的访问。

## 快速入门

向 Mastra Server 配置添加 Auth Provider。以下示例使用 [Simple Auth](https://mastra.zisheng.pro/docs/server/auth/simple-auth) 完成最小设置：

```typescript
import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      users: {
        'my-api-key': {
          id: 'user-1',
          name: 'Alice',
          role: 'admin',
        },
      },
    }),
  },
})
```

配置后，Studio 会显示登录页面，并要求所有 API 请求完成身份验证。有关支持的 Provider 完整列表，请参阅 [Auth 文档](https://mastra.zisheng.pro/docs/server/auth)。

## 工作原理

设置 [`server.auth`](https://mastra.zisheng.pro/reference/configuration) 会同时执行两项操作：

- **Studio UI**：显示登录页面。根据 Provider 的不同，用户可通过 SSO、邮箱/密码或两者登录。
- **API 路由**：要求所有内置路由（`/api/agents/*`、`/api/workflows/*` 等）和自定义路由完成身份验证。无论请求来自 Studio 还是直接 API 调用，此规则都适用。

Studio 通过调用 `GET /api/auth/capabilities` endpoint 检测可用能力。响应会告知 Studio 应渲染哪些登录方式；如果用户已通过身份验证，还会包含其用户信息和权限。

## 通过 URL 传递 token

当另一个应用嵌入或链接到 Studio 时，可以通过 `auth_header` URL 参数传递授权 token。当外部 Host 已持有 token，并希望直接打开已通过身份验证的 Studio 会话而不显示登录页面时，这种方式很有用。

`auth_header` 值始终用于填充 `Authorization` 请求 header。该参数只设置这一个 header，因此值中需要包含 Server 预期的任何 scheme 前缀，例如 `Bearer`。

使用查询字符串中的 token 打开 Studio：

```text
https://your-studio-host/?auth_header=Bearer%20your-token
```

Studio 会按以下方式处理 token：

- 加载时读取一次 `auth_header`，并在该会话的每个 API 请求中将其值作为 `Authorization` header 发送。
- 从地址栏中移除 `auth_header`，同时保留其他查询参数和 hash。
- 仅在内存中保存 token，绝不会将其写入本地存储，因此 token 保持临时状态，不会跨页面重新加载而持久存在。

Token 通过 URL 参数传递，因此 Host 应用负责该 URL 的生成和传输方式。URL 参数可能通过浏览器历史记录、referrer header 和 Server 访问日志暴露。

## 基于角色的访问控制

RBAC 用于控制每个用户在 Studio 中可以看到和执行的操作。它与身份验证分离：`server.auth` 处理用户身份，而 `server.rbac` 处理用户可以执行的操作。

### 默认角色

Mastra 包含四种默认角色。请从 `@mastra/core/auth/ee` 导入：

| 角色       | 权限          |
| -------- | ----------- |
| `owner`  | 完全访问权限（`*`） |
| `admin`  | 读取、写入和执行    |
| `member` | 读取和执行       |
| `viewer` | 只读          |

### 启用 RBAC

将 `StaticRBACProvider` 与默认角色配合使用，或定义自己的角色：

```typescript
import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'
import { StaticRBACProvider, DEFAULT_ROLES } from '@mastra/core/auth/ee'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      users: {
        'admin-key': { id: 'user-1', name: 'Alice', role: 'admin' },
        'viewer-key': { id: 'user-2', name: 'Bob', role: 'viewer' },
      },
    }),
    rbac: new StaticRBACProvider({
      roles: DEFAULT_ROLES,
      getUserRoles: user => [user.role],
    }),
  },
})
```

启用 RBAC 后，Studio 会隐藏用户无权执行的操作。Viewer 看不到删除按钮，member 无法修改 Agent 配置。

### 权限格式

权限遵循 `{resource}:{action}` 模式，并可选择限定到资源级别：

| 模式                  | 含义              |
| ------------------- | --------------- |
| `*`                 | 对所有内容拥有完全访问权限   |
| `*:read`            | 读取所有资源          |
| `agents:*`          | 对 Agent 执行所有操作  |
| `agents:execute`    | 仅执行 Agent       |
| `agents:read:my-id` | 按 ID 读取特定 Agent |

资源包括 `agents`、`workflows`、`tools`、`datasets`、`memory`、`scores`、`observability` 等。操作包括 `read`、`write`、`execute` 和 `delete`。

### 映射外部 Provider 角色

如果身份 Provider 已定义角色（例如 Clerk organization 或 WorkOS group），请使用 `roleMapping` 将其映射到 Mastra 权限：

```typescript
import { StaticRBACProvider } from '@mastra/core/auth/ee'

const rbac = new StaticRBACProvider({
  roleMapping: {
    'org:admin': ['*'],
    'org:member': ['*:read', '*:execute'],
    'org:viewer': ['*:read'],
  },
  getUserRoles: user => user.providerRoles,
})
```

## 登录方式

Studio 会根据 Auth Provider 调整登录页面：

| Provider 类型 | 登录 UI                           |
| ----------- | ------------------------------- |
| 仅 SSO       | SSO 按钮（例如“Sign in with WorkOS”） |
| 仅凭据         | 邮箱和密码表单                         |
| 两者兼有        | SSO 按钮和邮箱/密码表单                  |

可以按 Provider 启用或禁用注册。禁用后，Studio 会隐藏注册链接，并强制显示登录表单。

## EE 许可

Studio Auth 功能（SSO 登录、RBAC、基于权限的 UI）属于 Mastra Enterprise Edition。在使用 Simple Auth 或本地运行时，license 为可选项。使用第三方 Provider 的生产部署需要从 [Mastra 销售团队](https://mastra.ai/contact)获取有效的 EE license。

## 相关内容

- [Auth 概述](https://mastra.zisheng.pro/docs/server/auth)：支持的 Auth Provider 完整列表。
- [Studio 部署](https://mastra.zisheng.pro/docs/studio/deployment)：将 Studio 部署到生产环境。
- [自定义 API 路由](https://mastra.zisheng.pro/docs/server/custom-api-routes)：控制各个 endpoint 的身份验证。