Studio 身份验证

在 Mastra Server 上配置身份验证后，Studio 会自动显示登录页面并强制执行访问控制。一项配置即可同时保护 Studio UI 和 API 路由。

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

何时使用 Studio Auth

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

快速入门

向 Mastra Server 配置添加 Auth Provider。以下示例使用 Simple Auth 完成最小设置：

src/mastra/index.ts

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 文档。

工作原理

设置 server.auth 会同时执行两项操作：

• 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：

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 与默认角色配合使用，或定义自己的角色：

src/mastra/index.ts

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 权限：

src/mastra/index.ts

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 销售团队获取有效的 EE license。

相关内容

• Auth 概述：支持的 Auth Provider 完整列表。
• Studio 部署：将 Studio 部署到生产环境。
• 自定义 API 路由：控制各个 endpoint 的身份验证。