Studio auth

当你在 Mastra 服务器上配置认证后，Studio 会自动显示登录界面并强制执行访问控制。一次配置即可同时保护 Studio UI 和 API 路由。

如果不配置认证，Studio 和所有 API 路由都是公开可访问的。

备注

部署在 Mastra platform 上的 Studio 工作方式不同。默认情况下，platform 会注入自己的认证，因此只有你的组织成员可以登录，而你的 server.auth 仅适用于 API 路由。设置 MASTRA_PLATFORM_STUDIO_AUTH=disabled 可以选择退出。参见 Mastra platform 上的认证。

何时使用 Studio 认证

• 多个团队成员需要通过共享的 Studio 部署与 agents、workflows 和 tools 交互。
• 需要限制谁可以执行 agents 或编辑 workflows，或者删除 datasets 的权限。
• 登录界面（SSO、邮箱/密码或两者兼有）应该作为访问 Studio 部署的门槛。

快速开始

在 Mastra 服务器配置中添加一个认证提供方。下面这个例子使用 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 请求进行认证。访问认证文档查看受支持提供方的完整列表。

工作原理

设置 server.auth 会同时实现两件事：

• Studio UI：显示登录界面。根据提供方的不同，用户通过 SSO、邮箱/密码或两者登录。
• API 路由：要求所有内置路由（/api/agents/*、/api/workflows/* 等）和自定义路由进行认证。无论请求来自 Studio 还是直接 API 调用，都适用此规则。

Studio 通过调用 GET /api/auth/capabilities 端点来检测可用的能力。响应会告诉 Studio 应渲染哪些登录方式；如果用户已经通过认证，响应中还会包含用户信息和权限。

通过 URL 传递 token

当另一个应用嵌入或链接到 Studio 时，可以通过 auth_header URL 参数传入授权 token。当外部宿主已经持有 token，并希望打开一个已认证的 Studio 会话而不显示登录界面时，这非常有用。

auth_header 的值总是会被填入 Authorization 请求头。该参数只设置这一个请求头，因此请在值中包含服务器期望的任何 scheme 前缀，例如 Bearer。

在查询字符串中携带 token 打开 Studio：

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

Studio 按以下方式处理 token：

• 它在加载时读取一次 auth_header，并在该会话的每个 API 请求中把该值作为 Authorization 头发送。
• 它会从地址栏中移除 auth_header，同时保留其他查询参数和 hash。
• token 仅保存在内存中，从不写入本地存储，因此不会跨页面刷新持久化。

token 通过 URL 参数传输，因此宿主应用需要负责该 URL 的生成和传输方式。URL 参数可能通过浏览器历史记录、referrer 头以及服务器访问日志泄露。

基于角色的访问控制

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:*	对 agents 的所有操作
agents:execute	仅执行 agents
agents:read:my-id	按 ID 读取特定 agent

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

映射外部提供方角色

如果你的身份提供方已经定义了角色（例如 Clerk 组织或 WorkOS 分组），可以通过 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 会根据认证提供方调整登录界面：

提供方类型	登录 UI
仅 SSO	SSO 按钮（例如 “Sign in with WorkOS”）
仅凭据	邮箱和密码表单
两者	SSO 按钮和邮箱/密码表单

注册功能可以按提供方启用或禁用。禁用时，Studio 会隐藏注册链接并强制显示登录表单。

EE 许可

Studio Auth 功能（SSO 登录、RBAC、基于权限的 UI）属于 Mastra Enterprise Edition 的一部分。使用 Simple Auth 或在本地运行时，许可证是可选的。使用第三方提供方的生产部署需要从 Mastra 销售团队获取有效的 EE 许可证。

相关内容

• 认证概览：受支持认证提供方的完整列表。
• Studio 部署：将 Studio 部署到生产环境。
• 自定义 API 路由：控制单个端点的认证。