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

# Studio Auth

Mastra サーバーで[認証](https://mastra.zisheng.pro/ja/docs/server/auth)を設定すると、Studio は自動的にログイン画面を表示し、アクセス制御を適用します。1つの設定で Studio UI と API ルートの両方を保護できます。

認証を設定しない場合、Studio とすべての API ルートは一般公開されます。

## Studio Auth を使用する場面

- 複数のチームメンバーが、共有の Studio デプロイから Agent、Workflow、Tool を操作する必要がある。
- Agent を実行できるユーザー、Workflow を編集できるユーザー、またはデータセットを削除できるユーザーを権限で制限する必要がある。
- ログイン画面（SSO、メールアドレスとパスワード、またはその両方）で Studio デプロイへのアクセスを制限する必要がある。

## クイックスタート

Mastra サーバー設定に Auth Provider を追加します。次の例では、最小構成として [Simple Auth](https://mastra.zisheng.pro/ja/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/ja/docs/server/auth)を参照してください。

## 仕組み

[`server.auth`](https://mastra.zisheng.pro/ja/reference/configuration) を設定すると、次の2つが同時に有効になります。

- **Studio UI**：ログイン画面を表示します。Provider に応じて、ユーザーは SSO、メールアドレスとパスワード、またはその両方でサインインします。
- **API ルート**：すべての組み込みルート（`/api/agents/*`、`/api/workflows/*` など）とカスタムルートで認証を要求します。Studio からのリクエストにも、API の直接呼び出しにも適用されます。

Studio は `GET /api/auth/capabilities` エンドポイントを呼び出して、利用可能な機能を検出します。レスポンスに基づいて表示するログイン方法を決定し、ユーザーがすでに認証済みの場合はユーザー情報と権限も取得します。

## URL でトークンを渡す

別のアプリケーションから Studio を埋め込む場合やリンクする場合は、`auth_header` URL パラメーターで認証トークンを渡せます。外部ホストがすでにトークンを保持していて、ログイン画面を表示せずに認証済みの Studio セッションを開く場合に便利です。

`auth_header` の値は常にリクエストの `Authorization` ヘッダーに設定されます。このパラメーターで設定されるのはそのヘッダーだけです。サーバーが `Bearer` などのスキームプレフィックスを要求する場合は、値に含めてください。

クエリ文字列にトークンを指定して Studio を開きます。

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

Studio はトークンを次のように処理します。

- 読み込み時に `auth_header` を一度だけ読み取り、そのセッションのすべての API リクエストで値を `Authorization` ヘッダーとして送信します。
- その他のクエリパラメーターとハッシュを維持したまま、アドレスバーから `auth_header` を削除します。
- トークンはメモリ内だけに保持し、ローカルストレージには書き込みません。そのためトークンは一時的なもので、ページを再読み込みすると失われます。

トークンは URL パラメーターで渡されるため、その URL の生成方法と送信方法はホストアプリケーション側で管理してください。URL パラメーターは、ブラウザー履歴、リファラーヘッダー、サーバーのアクセスログに記録される可能性があります。

## ロールベースのアクセス制御

RBAC を使用すると、各ユーザーが Studio 内で表示および実行できる操作を制御できます。RBAC は認証とは別のものです。`server.auth` はユーザーが誰かを確認し、`server.rbac` はユーザーが何を実行できるかを制御します。

### デフォルトロール

Mastra には4つのデフォルトロールがあります。`@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 のロールをマッピングする

ID 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 の使用時やローカル実行時はライセンスを省略できます。サードパーティ Provider を使用する本番デプロイには、[Mastra 営業チーム](https://mastra.ai/contact)が発行する有効な EE ライセンスが必要です。

## 関連情報

- [Auth の概要](https://mastra.zisheng.pro/ja/docs/server/auth)：対応する Auth Provider の全一覧。
- [Studio のデプロイ](https://mastra.zisheng.pro/ja/docs/studio/deployment)：Studio を本番環境にデプロイします。
- [カスタム API ルート](https://mastra.zisheng.pro/ja/docs/server/custom-api-routes)：エンドポイントごとに認証を制御します。