管理ロールと権限（RBAC）

対象読者： スーパーアドミンダッシュボードの一部を、完全なスーパー管理者権限を渡すことずに委任したいプラットフォームオーナーとスーパー管理者。

この機能とは

歴史的に、AAEKB におけるスーパー管理者アクセスは全か無かでした。アカウントは完全なスーパー管理者（すべてのタブ、すべてのアクション、プラットフォーム全体）か、狭い Monitoring フラグ（読み取り専用の Logs & Auditing）を持つかのいずれかで、その中間はありませんでした。

Super Admin RBAC はその二値を管理ロールに置き換えます。管理ロールは、スーパーアドミンダッシュボードの各サーフェスにわたる権限の名前付きバンドルです。ユーザーに管理ロールをちょうど1つ割り当てると、そのロールが次を決定します：

• スーパーアドミンサイドバーにどのタブが表示されるか、
• それらの各タブが完全に操作可能か読み取り専用か、
• トップナビゲーションに Super Admin のエントリがそもそも表示されるか。

4つのロールが事前構成付きで同梱され、必要数のカスタムロールを定義できます。管理ロールを持たないユーザーは通常の AAEKB ユーザーです：Super Admin のエントリもダッシュボードもありません。

情報

これはプラットフォーム全体の管理であり、チームやプロジェクトの権限ではありません。チームロール（Owner / Admin / Editor / Member）とプロジェクトロールは別の無関係のシステムです。管理ロールはスーパーアドミンダッシュボードのみを支配します。

前提条件

• Admin Roles タブを開くには Admin Roles → View が必要で、その内容を変更するには Admin Roles → Manage が必要です。完全なスーパー管理者はデフォルトで両方を持ちます。
• ディレクトリリンク：/admin/super?tabName=roles（エイリアス ?tabName=admin_roles も有効）。

何かを設定する前に必要な概念

リソースとアクション

権限はペアです：リソース（Users や Teams のようなスーパーアドミンのサーフェス）と、それに対して実行できるアクション。

アクション	マトリックスの列	意味
view	View	サーフェスを読む。タブを開く、閲覧、検索、フィルタ、詳細パネルの表示。
manage	Manage	サーフェスの完全な作成 / 更新 / 削除。以下すべてを含む。
user_manage	User mgmt	メンバーのみを管理 — 追加、削除、ロール変更、オーナーの再割り当て。Manage の部分集合で、Teams と Projects で利用可能。
export	Export	サーフェスのデータを CSV/XLSX でダウンロード。Logs & Auditing で利用可能。

すべてのアクションがすべてのリソースに適用されるわけではありません。ロールビルダーでは、適用できない組み合わせはチェックボックスの代わりにダッシュ（—）で表示されます。

アクションの階層

チェックは直感的ではない — 一部のアクションは他のものを満たします：

チェック対象	ロールが以下を持つと合格
view	そのリソースの任意のアクション（Manage だけをチェックしても View を含意）
manage	manage
user_manage	user_manage または manage
export	export または manage

実務的な帰結：Manage をチェックすれば常に十分です。 併せて View をチェックする必要は決してありません。本当に読み取り専用のグラントが欲しいときだけ View を単独でチェックしてください。

ユーザーのアクセスがどのように解決されるか

割り当てられたロールが真実の拠り所です。レガシーの super-admin / monitoring フラグは、この機能より前に存在したアカウントの後方互換フォールバックとしてのみ保持され、組み込みの Super Admin または Monitoring ロールを割り当てたときは常に自動的に同期されます。

4つの組み込みロール

これらは自動的にシードされ、ロールテーブルで System とマークされます。権限は固定で編集も削除もできません — 組織が異なる用語を使う場合、名前と説明は変更できます。それらの変種が必要な場合は、代わりにカスタムロールを作成してください。

ロール	権限	保持者が得るもの
Super Admin	すべてのアクセス	すべて。レガシーの super-admin フラグと同一。
Monitoring	Logs & Auditing → View	Logs & Auditing のみ、読み取り専用、エクスポートなし。レガシーの monitoring フラグと同一。
Project Manager	Projects → View、Manage、User mgmt	Projects タブ、完全に操作可能：作成、編集、クローン、転送、プロジェクトの所属とロールの管理。
User Access Manager（UAM）	Access Controls → View、Manage；Users → View、Manage；Teams → User mgmt；Projects → User mgmt	Users と Access Controls は完全に操作可能；Teams は読み取り専用で表示。下記の注意をご覧ください。

情報

UAM ロールに関する注意。 その Teams と Projects への user_manage グラントは API に尊重されますが、ダッシュボードのタブ表示ルールにより、Projects タブは表示されず（Manage が必要）、Teams タブは読み取り専用で開きます（メンバー管理コントロールは非表示）。したがって UAM ユーザーは、Teams や Projects ではなく、Users タブと Access Controls でユーザーを管理します。Teams タブから本当にチームメンバーを管理できるロールが必要な場合は、Teams → Manage のカスタムロールを作成してください。

権限リファレンス

ロールビルダーに表示される順序どおりの完全なマトリックスです。

エンドツーエンドで機能する権限

これらはダッシュボードと API の両方によって一貫して強制されます。委任ロールの構築にはこれらを使用してください。

リソース	アクション	解錠されるタブ	表示条件	与えるもの
Users	View、Manage	Users	View	View： すべてのユーザーの閲覧と検索、チーム情報と SAML メタデータの表示、ログイン IP の表示。Manage： ユーザー詳細の編集、ユーザーの削除、ユーザーの作成、非アクティブ再有効化リクエストの承認/却下、ユーザーリストのエクスポート。（エクスポート API は View のみを要求しますが、タブが読み取り専用の間はボタンが非表示のため、それを表示するのは Manage です。）
Teams	View、Manage、User mgmt	Teams	View	View： チーム、詳細、メンバー、設定、請求、チームログの閲覧。Manage： チーム、サブドメイン、設定の作成/編集/削除、ライセンス更新、オーナー転送。User mgmt： チームメンバーの追加、削除、ロール変更（API レベル；上記の UAM の注意参照）。
Projects	View、Manage、User mgmt	Projects	Manage	View： すべてのプロジェクトの閲覧、検索、検査。Manage： プロジェクトのクローン、チーム間の転送。User mgmt： プロジェクトメンバーの追加/削除、メンバーロールの変更、プロジェクトオーナーの変更。
Access Controls	View、Manage	Access Controls	View	View： 現在のサインインアクセスモード、「Require pre-authorized account」設定、すべての SAML アクセスルールの表示。Manage： アクセスモードの切り替え、事前認証ロックダウンのトグル、SAML アクセスルールの作成/編集/削除。
Logs & Auditing	View、Export	Logs & Auditing	View	View： すべての監査サーフェスの読取 — チャット、ユーザー、アクセス、ツール、セキュリティ、チーム、SSO、設定、エージェントテンプレート、スーパー管理者アクションログ。Export： エクスポートボタンの非表示を解除 — ただし監査ログのエクスポートは委任できないをご覧ください、エクスポートエンドポイント自体は完全なスーパー管理者に限定されたまま。
Admin Roles	View、Manage	Admin Roles	View	View： すべてのロールとその権限の表示；Users タブの管理ロールピッカーを使用するためにも必要。Manage： カスタムロールの作成、編集、削除、および任意のユーザーの割り当て済み管理ロールの変更。
Custom Toolkits	View、Manage	（タブなし — 現在非表示）	—	Manage： API 経由でチーム間にわたるプラットフォーム全体のカスタムツールキットの作成と共有。スーパーアドミンヘッダーの Admin Assistant を使うためにも必要。

現在ダッシュボードのみを制御する権限

これらのリソースは対応するタブを表示しますが、基盤の API はまだ完全なスーパー管理者に限定されています。これらだけを与えたユーザーはタブを見て、「Unauthorized」エラーに当たります。

警告

これらに基づいて委任ロールをまだ構築しないでください。マトリックスが謎めかないように、ここにリストしています。

リソース	現れるタブ	状態
Overview	（なし）	完全に無効。Overview タブはいずれにせよ完全なスーパー管理者専用。
Agents	Agents	UI ゲートのみ — API は完全なスーパー管理者を要求。
SSO Configuration	SSO Configuration	UI ゲートのみ — API は完全なスーパー管理者を要求。
Knowledge Base	Knowledge Base	UI ゲートのみ — API は完全なスーパー管理者を要求。
Templates	Agent Templates、Workflow Templates、Project Templates	UI ゲートのみ — API は完全なスーパー管理者を要求。
Toolkits	Toolkits	UI ゲートのみ — API は完全なスーパー管理者を要求。
Secrets	Secrets、Vault	UI ゲートのみ — API は完全なスーパー管理者を要求。
Platform Settings	Platform Settings	UI ゲートのみ — API は完全なスーパー管理者を要求。

決して委任できないサーフェス

これらはマトリックスに権限がなく、設計上完全なスーパー管理者のために予約されています：Overview、App Licenses、Teams Bots、LLM Metrics、LLM Usage、Extract Usage、Email Configuration、KB Decryption Service、Migrations、System、Task Monitor、Global Notifications、Custom Python Packages。

Custom Python Packages は意図的に除外され、完全なスーパー管理者に永続的にロックされています。パッケージのインストールはアプリアンスホスト上で任意のコードを実行するためです。

ロールが表示できるタブ

2つの異なるルールが適用され、ロール構築時の最も一般的な混乱の源です：

ルール	リソース	挙動
View で十分	Users、Teams、Access Controls、Logs & Auditing、Admin Roles	View を与えるとタブが安全な読み取り専用状態で表示されます。Manage を与えると完全に操作可能になります。
Manage が必要	Projects、Agents、SSO Configuration、Knowledge Base、Templates、Toolkits、Custom Toolkits、Secrets、Platform Settings	View だけを与えるとタブは隠れます。これらのタブにはまだ読み取り専用の処理がないため、view のみのグラントはユーザーが押してはならないライブボタンを表示してしまいます。

Projects に View をチェックしたのにタブが表示されない場合、それが理由です。Manage をチェックしてください。

読み取り専用の実際の見え方

読み取り専用モードを告知するバナーやバッジはありません。コントロールが単に存在しないか、グレーアウトしています。

タブ	完全に非表示	無効（表示されるがグレー）	まだ利用可能
Users	Create User、Export、Delete User	管理ロール割り当てピッカー、保留中の再有効化リクエストの承認/却下	検索、閲覧、ロールバッジ、View Team、View SAML、ログイン IP 詳細、ページネーション
Teams	Create Team、Edit Team、Delete Team、Renew Licence、Add/Remove Member、Transfer Ownership、Edit Settings、Automated Management 下のルール編集、Team Logs/Audit の Export	—	チームの検索とフィルタ、すべてのチーム詳細、メンバー一覧（ロールはプレーンテキスト表示）、設定、請求、ログと監査の閲覧
Access Controls	ルール編集と削除アイコン、「Add New Rule」セクション全体	「Allow Any New Users」カード、「Restrict to SAML Metadata」カード、「Require pre-authorized account」スイッチ	現在のモード、制限モードの警告、既存のすべての SAML ルール
Logs & Auditing	すべての監査ビューでの Export、監査機能カードの Enable スイッチ	—	すべてのフィルタ、閲覧、行の展開、詳細モーダル、Load More
Admin Roles	New Role、Save、Delete	名前と説明のフィールド、すべての権限チェックボックス	ロール一覧、および無効化されたエディターでロールを開く View ボタン

ステップごと

1. カスタムロールを作成

   1. Super Admin → Security & access → Admin Roles に移動します。
   2. New Role をクリックします。
   3. Name を入力します（例：Support Tier 2）。これはロールピッカーに表示されます。内部 id は名前から自動生成されます — 小文字で、スペースと句読点はアンダースコアに置換。
   4. Description を入力します。ロールテーブルで名前の下に表示されます；自分のためではなく次の管理者のために書いてください。
   5. 権限マトリックスで、リソースごとに欲しいアクションをチェックします。覚え方：Manage は View を含意 — 両方は不要；Users / Teams / Access Controls / Logs & Auditing / Admin Roles 以外のものは、タブを表示させるためにManage をチェックする必要がある；上記のダッシュボードのみリストのものはまだエンドツーエンドで機能しない。
   6. Save をクリックします。

   新しいロールは Custom とマークされてテーブルに現れ、Users タブのロールピッカーですぐに選択できるようになります。

2. ロールの編集と削除

   • 編集 — カスタムロールの Edit をクリックし、必要なことを変更し、Save。
   • システムロール — ボタンは Edit の代わりに View と表示され、マトリックスはロック。名前と説明は変更可能；権限は変更不可。
   • 削除 — カスタムロールの Delete をクリックして確認。現在それを持っている人は黙って割り当て解除され、スーパー管理者アクセスを完全に失います。再割り当てのプロンプトはないので、削除前に誰がそのロールを持っているか確認してください。

3. ユーザーにロールを割り当てる

   1. Super Admin → Users & workspaces → Users に移動します。
   2. ユーザーを見つけます（検索はユーザー ID、メール、名前を受け付けます）。
   3. その行で Assign admin role ドロップダウンを開き、ロールを選ぶか、No admin role ですべてのスーパー管理者アクセスを取り消します。
   4. プロンプトを確認します。プラットフォーム全体の特権の付与と取り消しは意図的に確認の裏に置かれおり、自分自身の降格には追加の警告が付きます — スーパーアドミンダッシュボードへのアクセスを直ちに失い、復元には別のスーパー管理者が必要です。

   ユーザーは最大で1つの管理ロールを持ちます。新しいロールの割り当ては以前のものを置き換えます。

   ここには2つの権限が関わります：ピッカーを埋めるには Admin Roles → View が必要（なければドロップダウンはグレーアウトし、ユーザーの現在のロールはプレーンなラベルで表示 — 組み込みの UAM ロールが管理ロールを割り当てられない理由がこれです）、誰かのロールを実際に変更するには Admin Roles → Manage が必要です。

4. 変更がいつ有効になるかを知る

   • あなたが他人に対して行う場合： 即時。サーバーはすべてのリクエストで権限を再解決するため、取り消しは影響ユーザーの次の API 呼び出しをブロックします。
   • 影響ユーザーのブラウザの場合： サイドバーとナビゲーションはサインイン時に取得しローカルにキャッシュされた権限データから描画されます。タブが現れたり消えたりするにはページを再読み込み（またはサインアウトして再サインイン）する必要があります。

   ロールを変更した後、ユーザーに更新を伝えてください。

計画すべき挙動と制限

タブ表示の非対称性

View が表示するのは5つのタブのみ（Users、Teams、Access Controls、Logs & Auditing、Admin Roles）；それ以外はすべて Manage が必要です。最小権限ロールを設計するときにこの点を考慮してください。

UAM ロールは UI からチームやプロジェクトの所属を管理できない

その user_manage グラントは API レベルでは実在しますが、Teams タブは読み取り専用でレンダリングされ、Projects タブは隠れます。UI ベースのチームメンバー管理が要件なら、カスタムロールで Teams → Manage を使用してください。

監査ログのエクスポートは委任できない

Logs & Auditing → Export をチェックするとエクスポートボタンの非表示は解除されますが、すべての監査エクスポートエンドポイントは依然として完全なスーパー管理者を要求するため、ダウンロードは「Unauthorized」で失敗します。当面、監査エクスポートは完全なスーパー管理者専用として扱ってください。読み取りアクセスは正しく委任されます。

いくつかのマトリックスリソースはダッシュボードのみ

Agents、SSO Configuration、Knowledge Base、Templates、Toolkits、Secrets、Platform Settings はタブを現わしますが、API は依然として完全なスーパー管理者を要求します。Overview は何の効果も持ちません。

レガシーフラグはまだ存在し、同期し続ける

Super Admin の割り当てはレガシーの super-admin フラグを設定；Monitoring の割り当てはレガシーの monitoring フラグを設定；その他のロールの割り当てやロールのクリアは両方をクリアします。これらのフラグを自分で管理する必要は決してなく、そう試みるべきでもありません — ロール割り当てが唯一のサポートされる経路です。

警告

自分を締め出すことを防ぐものは何もありません。管理者は自分の Super Admin ロールを削除できます。確認ダイアログは警告しますが、アクションは許可されています。すべてのデプロイで完全なスーパー管理者を2人以上維持してください。

レシピ

要件	構成
人々をルックアップできるが何も変更できないヘルプデスク	カスタムロール：Users → View
アカウントの編集と無効化もできるヘルプデスク	カスタムロール：Users → Manage
ID 管理者（組み込みの UAM 形）	User Access Manager を割り当て、または Users → Manage、Access Controls → Manage のカスタムロール
管理ロールも割り当てられる ID 管理者	カスタムロール：Users → Manage、Access Controls → Manage、Admin Roles → Manage
Teams タブから所属を管理するチーム管理者	カスタムロール：Teams → Manage（User mgmt だけでは不十分）
プロジェクト管理者	Project Manager を割り当て、または Projects → Manage のカスタムロール
コンプライアンス / 監査リーダー	Monitoring を割り当て、または Logs & Auditing → View のカスタムロール。エクスポートは委任不可。
ユーザーとチームのレコードも読む必要のある監査者	カスタムロール：Logs & Auditing → View、Users → View、Teams → View

監査

すべての管理ロールの変更はスーパーアドミンアクション監査ログに書き込まれ、Super Admin → Usage & auditing → Logs & Auditing → Super Admin audits で表示できます。

イベント	記録されるタイミング
admin_role_created	カスタムロールが作成された（権限マップ付き）
admin_role_updated	ロールの名前、説明、権限が変更された
admin_role_deleted	カスタムロールが削除された
super_admin_granted / super_admin_revoked	ユーザーが完全な Super Admin ロールを得た／失った
monitoring_role_granted / monitoring_role_revoked	ユーザーが Monitoring ロールを得た／失った
admin_role_changed	その他のロール割り当ての変更、以前と新しいロールを記録

ロール割り当てイベントは実行者、対象ユーザー、変更前後のロールを記録します。

テストチェックリスト

• 単一の狭い権限（例：Users → View）のテスト用カスタムロールを作成し、テストアカウントにタブが読み取り専用で表示されることを確認
• Manage 必須リソース（例：Projects）が View のみのときは隠れたまま、Manage を与えると表示されることを確認
• テストユーザーにロールを割り当て、サイドバーが更新される前にブラウザの再読み込みが必要であることを確認
• システムロールの権限を編集しようとして拒否されることを確認
• 誰かに割り当て済みのカスタムロールを削除し、黙って管理ロールなしに落ちることを確認
• 各ロール変更がスーパーアドミン監査ログに正しく表示されることを確認
• カスタムロールを配布する前に、少なくとも2つのアカウントが完全な Super Admin を保持していることを確認

トラブルシューティング

症状	原因	修正
ユーザーはロールを持つがナビゲーションに Super Admin エントリが見えない	ロールが表示可能タブに対応するものを何も与えていない（例：Manage 必須リソースの View のみ）、またはブラウザの権限キャッシュが古い	上記の権限リファレンスとロールを照合；ユーザーにページの再読み込みを依頼
与えたタブが表示されない	リソースは表示に Manage を要求	View の代わりに Manage をチェック
タブは表示されるがすべて「Unauthorized」で失敗	リソースがダッシュボードのみを制御	上記のダッシュボードのみリストを参照 — そのリソースはまだ委任不可
ユーザーが開けるタブでボタンが欠けている	タブが読み取り専用モード：View はあるが Manage がない	そのリソースに Manage を与える
Logs & Auditing の Export ボタンがない	読み取り専用モード — Export 権限なし	Export を与える。ダウンロードはそれでも失敗することに注意（監査エクスポートは委任不可）
Export ボタンはあるがダウンロードが失敗	監査エクスポートは完全なスーパー管理者を要求	上記の「監査ログのエクスポートは委任できない」を参照
Assign admin role ドロップダウンがグレーアウト	実行中の管理者に Admin Roles → View がなく、ロール一覧をロードできない	Admin Roles → View を与える（ロールを実際に変更するには Manage も）
ユーザーの管理ロール変更が「Unauthorized」を返す	実行中の管理者に Admin Roles → Manage がない	Admin Roles → Manage を与える
「システムロールの権限は変更できません」	システムロールの権限は固定	欲しい権限でカスタムロールを作成
「システムロールは削除できません」	4つの組み込みロールは保護されている	代わりにユーザーから割り当て解除
ロール変更がユーザーに有効にならない	クライアントが古い権限をキャッシュ	再読み込み、またはサインアウトして再サインインを依頼
既存のスーパー管理者がアップグエード後にアクセスを失った	起こらないはず — 既存の保持者は自動移行済み	別の完全なスーパー管理者アカウントで Users タブから Super Admin ロールを再割り当て

運用ガイド

アップグエード時の挙動

機能がデプロイされると、既存の特権保持者は自動的に移行されます：

• レガシーの super-admin フラグを持つアカウントは Super Admin ロールを割り当てられます。
• レガシーの monitoring フラグのみを持つアカウントは Monitoring ロールを割り当てられます。
• その他のすべてのアカウントは管理ロールなしのままです。

アクションは不要で、アップグエード中に誰もアクセスを失いません。

API リファレンス

すべてのエンドポイントは管理 API 配下にあり、記載された権限を持つユーザーのベアラートークンを要求します。

メソッドとパス	権限	目的
GET /admin/permissions	roles:view	リソースのカタログと各リソースで有効なアクション — ロールビルダーがレンダリングするもの
GET /admin/roles	roles:view	すべてのロールを一覧
POST /admin/roles	roles:manage	カスタムロールの作成
PUT /admin/roles/{role_id}	roles:manage	ロールの更新（システムロールでは権限は拒否）
DELETE /admin/roles/{role_id}	roles:manage	カスタムロールの削除（システムロールは拒否）
PUT /admin/users/{user_id} で {"admin_role_id": "..."}	roles:manage	ロールの割り当て；null でクリア
GET /user/info	認証済み	呼び出し側の admin_role_id と実効 admin_permissions を返す

ロールの権限は、リソースをアクションのリストにマップする JSON オブジェクトです。全アクセスのワイルドカードは {"*": ["*"]}。未知のリソース、またはそのリソースに無効なアクションでロールを作成すると HTTP 400 で拒否されます。

例 — 組み込みの User Access Manager：

{
  "access_controls": ["view", "manage"],
  "users": ["view", "manage"],
  "teams": ["user_manage"],
  "projects": ["user_manage"]
}

例 — 読み取り専用のヘルプデスクロールの作成：

POST /admin/roles
{
  "name": "Help Desk",
  "description": "Read-only access to user records for first-line support.",
  "permissions": { "users": ["view"] }
}

権限マトリックス一覧

リソース	View	Manage	User mgmt	Export	タブの表示条件	完全な強制
Overview	✓	—	—	—	決して	効果なし
Users	✓	✓	—	—	View	はい
Teams	✓	✓	✓	—	View	はい
Projects	✓	✓	✓	—	Manage	はい
Agents	✓	✓	—	—	Manage	UI のみ
Access Controls	✓	✓	—	—	View	はい
SSO Configuration	✓	✓	—	—	Manage	UI のみ
Logs & Auditing	✓	—	—	✓	View	view のみ
Knowledge Base	✓	✓	—	—	Manage	UI のみ
Templates	✓	✓	—	—	Manage	UI のみ
Toolkits	✓	✓	—	—	Manage	UI のみ
Custom Toolkits	✓	✓	—	—	タブなし	はい（API）
Secrets	✓	✓	—	—	Manage	UI のみ
Platform Settings	✓	✓	—	—	Manage	UI のみ
Admin Roles	✓	✓	—	—	View	はい

情報

ドキュメントバージョン1.0 — 出荷時およびその後の修正を含む Super Admin RBAC 機能を対象とします。上記のダッシュボードのみの権限とエクスポート制限は執筆時点の既知の制限を反映しています；それに依存する前に、デプロイ済みリリースに対して検証してください。