Studio 驗證

在 Mastra 伺服器上設定驗證後，Studio 會自動顯示登入畫面並實施存取控制。一項設定即可同時保障 Studio UI 和 API 路由安全。

如未設定驗證，任何人都可公開存取 Studio 及所有 API 路由。

何時使用 Studio Auth

• 多名團隊成員需要透過共用的 Studio 部署與 Agent、Workflow 和 Tool 互動。
• 必須以權限限制哪些人可以執行 Agent、編輯 Workflow，或刪除資料集。
• 應以登入畫面（SSO、電郵／密碼，或兩者）限制 Studio 部署的存取。

快速開始

在 Mastra 伺服器設定中加入驗證 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。

運作方式

設定 server.auth 會同時執行兩項操作：

• Studio UI：顯示登入畫面。視乎 Provider，使用者可透過 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 header。此參數只會設定這一個 header，因此值中必須包含伺服器預期的任何 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 參數傳送，因此主機應用程式須負責產生及傳輸該 URL 的方式。URL 參數可能會透過瀏覽器記錄、referrer header 及伺服器存取記錄外洩。

角色存取控制

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 組織或 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 會按驗證 Provider 調整登入畫面：

Provider 類型	登入 UI
只限 SSO	SSO 按鈕（例如「Sign in with WorkOS」）
只限憑證	電郵及密碼表格
兩者	SSO 按鈕及電郵／密碼表格

每個 Provider 均可啟用或停用註冊功能。停用後，Studio 會隱藏註冊連結，並強制顯示登入表格。

EE 授權

Studio Auth 功能（SSO 登入、RBAC、按權限顯示 UI）屬於 Mastra Enterprise Edition。使用 Simple Auth 或在本機運行時，授權屬選用項目。使用第三方 Provider 的正式環境部署，則須向 Mastra 銷售團隊取得有效的 EE 授權。

相關內容

• 驗證概覽：所有支援的驗證 Provider 完整清單。
• Studio 部署：將 Studio 部署至正式環境。
• 自訂 API 路由：控制個別端點的驗證。