Studio Auth

Mastra サーバーで認証を設定すると、Studio は自動的にログイン画面を表示し、アクセス制御を適用します。1つの設定で Studio UI と API ルートの両方を保護できます。

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

Studio Auth を使用する場面

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

クイックスタート

Mastra サーバー設定に 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 を設定すると、次の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 を開きます。

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 を使用するか、独自のロールを定義します。

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 のロールをマッピングする

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

関連情報

• Auth の概要：対応する Auth Provider の全一覧。
• Studio のデプロイ：Studio を本番環境にデプロイします。
• カスタム API ルート：エンドポイントごとに認証を制御します。