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

# Studio 驗證

在 Mastra 伺服器上設定[驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth)後，Studio 會自動顯示登入畫面並實施存取控制。一項設定即可同時保障 Studio UI 和 API 路由安全。

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

## 何時使用 Studio Auth

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

## 快速開始

在 Mastra 伺服器設定中加入驗證 Provider。以下範例使用 [Simple Auth](https://mastra.zisheng.pro/zh-HK/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 請求均須通過驗證。請參閱[驗證文件](https://mastra.zisheng.pro/zh-HK/docs/server/auth)，了解所有支援的 Provider。

## 運作方式

設定 [`server.auth`](https://mastra.zisheng.pro/zh-HK/reference/configuration) 會同時執行兩項操作：

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

```text
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`，或自行定義角色：

```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 組織或 WorkOS 群組），可使用 `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 會按驗證 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 銷售團隊](https://mastra.ai/contact)取得有效的 EE 授權。

## 相關內容

- [驗證概覽](https://mastra.zisheng.pro/zh-HK/docs/server/auth)：所有支援的驗證 Provider 完整清單。
- [Studio 部署](https://mastra.zisheng.pro/zh-HK/docs/studio/deployment)：將 Studio 部署至正式環境。
- [自訂 API 路由](https://mastra.zisheng.pro/zh-HK/docs/server/custom-api-routes)：控制個別端點的驗證。