ユーザー・ロール・SSO

Yagra は最初のリリースからロールベースのアクセス制御を備えています。ローカル、SSO による自動作成、API トークン — どのアカウントも 3 つのロールのいずれかを持ち、状態を変えるすべての操作は権限が検査され、状態を変えたことはすべて監査ログに残ります。このページはアクセス制御の全体を扱います。ロールと権限、ローカルアカウントとそのセッションのライフサイクル、シングルサインオン、 API トークン、そして公開ダッシュボードモードがそれらとどう絡むかです。

ロール

ロールは 3 つで、権限は上へ行くほど積み上がります — 各ロールは、1 つ下のロールが持つものをすべて持ちます。

Viewer（閲覧者） — 読み取り専用。インベントリ、メトリクス、ダッシュボード、トポロジ、イベント、アラート。Viewer は WebUI が見せるものすべてを見られますが、何も変更できません。
Operator（オペレーター） — Viewer に加えてインシデント対応。アラートの確認（ACK）やミュート、トラブルシュート分析と AI による根本原因説明の実行、メンテナンスウィンドウの開始と終了。オンコール担当のロールです。
Admin（管理者） — 完全な制御。監視の設定、認証情報、ユーザー管理、そして監査ログ。

WebUI は設定 ▸ ロールと権限に、ロールと権限の完全なマトリクスを表示します。

以前のリリースでロールを割り当てた場合に知っておく価値のある、最近の変更が 1 つあります。 トラブルシュート分析の実行は、いまや Operator の操作です。 以前は REST API 経由では Admin が必要でした（その一方で、一貫性を欠くことに Viewer のトークンは MCP 経由で同じ分析を起動できました）。現在はどちらの入口でも、アラートの確認と同じインシデント対応の権限を求めます。分析は監視の履歴を読むだけで設定は一切変更しないので、オンコールのオペレーターに属する操作です。過去の実行とその分析結果の閲覧は変わらず Viewer にも開かれています — ただし Viewer スコープの API トークンは、もはや /mcp 経由で分析を起動できません。

権限とグループスコープ

ロールは権限の束です。全体は次のとおりです。

権限	何ができるか	Viewer	Operator	Admin
View	インベントリ・メトリクス・アラートの閲覧	✔	✔	✔
Respond to incidents	アラートの確認（ACK）やミュート、トラブルシュート分析の実行、AI による根本原因説明の依頼		✔	✔
Manage maintenance	メンテナンスウィンドウの開始と終了		✔	✔
Manage configuration	ノード・プロファイル・しきい値・収集の作成と編集			✔
Manage credentials	監視用の認証情報の作成・編集・ローテーション			✔
Manage users	ユーザーアカウントとロール割当の管理			✔
View audit	監査ログの閲覧（誰が何を変更したか）			✔

権限は個々のアカウントではなくロールに紐づきます — アカウントごとに 3 つのロールから 1 つを選べば、残りは上のマトリクスが決めます。

グループスコープ。 アカウントはロールと並んで可視性のスコープを持ちます。すべてのグループ、または指定したノードグループの集合です。スコープは、そのアカウントがインベントリのどの断面に関わるのかを宣言します — どのグループにも属していないノードは、すべてのグループを対象とするスコープの下にしか入りません。

API の読み取りエンドポイントは呼び出し元のグループスコープで絞り込みます。ノード一覧は許可されたグループとその配下に限定され、集計やランキングも同じ集合に絞られ、スコープ外のノードは 404 を返します — 存在しない ID と同じ応答なので、ID 空間の探索はできません。一部のエンドポイントにはノード単位の帰属が残っていない（レンダリング済みのレポート、集計済みのフリート推移など）ため、フリート全体の数値を黙って返す代わりにグループスコープの呼び出し元を拒否します。

スコープの割り当て。 設定 ▸ ユーザーの行アクション可視範囲を変更で、チェックしたグループだけにアカウントを限定できます。1 つもチェックしなければフリート全体に戻ります。アカウントは無制限の状態から始まります — SSO アカウントも同様で、初回サインイン時にプロビジョニングされてからここで絞り込みます。割り当てた内容は以後のログインでも保持されます。これは Yagra 側の決定であり、ディレクトリから毎回導出し直すものではないからです。

使う前に知っておくべきルールが 2 つあります:

Admin は絞り込めません。 管理操作はフリート全体に及ぶ — 管理者はどのノードでも再設定できる — ため、絞り込まれた管理者は「編集はできるのに一覧には出ないノード」を持つことになります。Admin へ昇格させると、保持していたスコープは解除されます。
グループを 1 つも指定しないスコープは拒否されます。 保存できてしまうと、サインインには成功するのに在庫が空で、その理由がどこにも出ないアカウントになるためです。

スコープを保存すると、そのアカウントの現行セッションはサインアウトされます。ロール変更と同じ理由で、スコープはセッショントークンに焼き込まれており、生きたトークンは古い広い範囲を保持し続けてしまうからです。

サインイン中のアカウントが制限されている場合は、アカウントメニューにその旨が表示されます — 範囲を絞られたオペレーターから見ると一覧が短くなるだけで、「3 サイトが見えている」のか「3 サイトしかない」のかを区別する手がかりが他に無いためです。

ローカルアカウント

新規インストールでは admin というローカルアカウントが 1 つ作られ、初回起動時にコアのログへ初期パスワードが一度だけ出力されます。

docker compose logs core   # look for the one-time admin password

それでサインインし、そのあと変更してください。ローカルアカウントの管理は設定 ▸ ユーザー で行います。ロールを指定したアカウントの作成、パスワードの変更やリセット（“Change password”）、アカウントの無効化、削除です。

セッションのライフサイクル。 ログインするとベアラのセッショントークンが発行され、WebUI が保持します。人を呼び出すシステムに期待されるとおりの方法で、セッションは堅牢化されています。

セッションは期限切れになります — 一定時間のアイドル後と、絶対的な有効期間の経過後の、早く訪れた方です。ログアウトするとトークンはサーバー側で即座に失効します。
管理者の操作はセッションを即座に断ちます。アカウントの無効化、ロールの降格、パスワードのリセット、削除のいずれもが、そのアカウントのアクティブなセッションをその場で無効にします — 発行済みのトークンが生き残ることはありません。
ログインのエンドポイントはブルートフォース対策を適用します。失敗を繰り返したアカウントごとの指数的なロックアウトに加えて、グローバルな試行レートの上限があるため、パスワード推測の実行は応答されるのではなく絞られます。

セッション署名鍵を共有する高可用性（HA）構成では、ログインはどのコアでも受け付けられ、コアの再起動やフェイルオーバーを越えて維持されます — そしてログアウト、無効化、ロール変更、パスワードのリセットは、すべてのコアに即座に反映されます。

シングルサインオン

Yagra は OpenID Connect で外部の ID プロバイダに対してユーザーをサインインさせます — Google Workspace、Microsoft Entra、Okta、Keycloak、その他 OIDC に対応した任意の IdP です。ローカルアカウントの代わりではなく、併用します。

プロバイダの設定は設定 ▸ 認証で行います。まず ID プロバイダの種別を選びます — Microsoft Entra ID / Okta / Google Workspace、その他の OIDC プロバイダなら「その他」 — そのうえで、その製品が実際に必要とする項目だけを尋ねます。8 個の自由入力欄を並べて「自分の IdP が何を求めるかは知っているはず」と仮定することは、もうしません。

Entra ID はディレクトリ（テナント）ID を尋ね、そこから Issuer URL を組み立てます。要求するスコープは標準の OIDC スコープだけです — Entra は標準外のスコープを問答無用で拒否するため、 groups を初期値に入れていた汎用フォームでは、そもそもサインイン画面に到達できませんでした。グループクレームはアプリ登録のトークン構成で有効にしてください（グループのオブジェクト ID として届きます）。
Okta は組織ドメインを尋ね、そこから Issuer URL を組み立て、org 認可サーバーが提供する groups スコープを要求します。カスタム認可サーバーは Issuer が異なるため「その他」に該当します。
Google Workspace は Issuer が 1 つなので URL の入力はありません。またグループ→ロールのマッピングはありません（意図的です）— Google は ID トークンにグループ所属を載せないため、それに対して設定したマッピングは決して一致しません。代わりに既定ロールが必須です。これが無いとすべてのサインインが拒否されてしまうためです。
その他は一式を直接尋ねます。IdP のアプリ登録から得た Issuer URL、クライアント ID、 クライアントシークレット、加えて Yagra がコールバックを受けるリダイレクト URLと、要求する スコープです。

Google Workspace を除き、プロバイダは IdP のグループから Yagra のロールへのマッピングを持ちます。ディレクトリ上の所属によって、その人が Viewer・Operator・Admin のどれになるかが決まります。

アカウントはジャストインタイムで作成されます。最初の SSO サインインが成功した時点で Yagra のアカウントが作られ、アカウントのロールは毎回のログインで IdP のグループマッピングに追従します — ディレクトリのグループ間で誰かを移動させれば、次のサインイン時に Yagra のロールが更新されます。プロバイダを有効にすると、ログイン画面に “Continue with SSO” ボタンが現れます。

クライアントシークレットは保存時にエンベロープ暗号で保護され、保存後に再表示されることはありません — Yagra が監視用の認証情報に与えているのと同じ扱いです。

LDAP / Active Directory

OIDC プロバイダではないディレクトリのために、Yagra は LDAP / Active Directory に対して直接サインインできます。設定は設定 ▸ 認証 ▸ ディレクトリ (LDAP/AD) で行います。別ボタンも別 URL もありません — 通常のログインフォームに社内アカウントの認証情報を入力するだけです。

Yagra はサービスアカウントで対象者を検索し、見つかったエントリの DN で再バインドするため、ディレクトリの構成に合わせて DN の組み立てパターンを当てる必要がありません。所属グループは SSO プロバイダと同じマッピング機構でロールに対応し、完全な DN でも名前だけでも一致します。アカウントは初回サインイン成功時に自動作成されます。

ローカルアカウントが常に先に試されます。 ディレクトリに到達できなくなっても管理者が締め出されることはありません — ローカル管理者を 1 つ残しておけばロールバックしても復帰できます。
LDAPS と StartTLS のみで、社内 CA の入力欄があります。証明書検証を無効化する手段は意図的に用意していません。
バインドパスワードは他のすべての秘密と同じく保存時にエンベロープ暗号化されます。
テストボタンは段階ごとに結果を報告し、ユーザー名を渡すと DN・グループ・そのユーザーが得るロールを表示します（「拒否される」場合も含みます — ログイン画面ではパスワード違いと区別が付かない状態です）。

ディレクトリアカウントが所有する API トークンは、SSO 所有のものと同じく所有者の沈黙で失効します（YAGRA_PAT_OIDC_IDLE_DAYS）。ディレクトリ側でのアカウント無効化は Yagra に通知されないため、所有者が来なくなることが唯一の手がかりだからです。

SAML には自前実装ではなくブリッジ構成で回答します — 前段に Keycloak か Dex を SAML→OIDC ブリッジとして置いてください。Yagra が XML 署名検証を自前で行うことはありません。

API トークン

無人のクライアント — MCP で接続する AI アシスタント、スクリプト、CI ジョブ — のために、Yagra は yat_ で始まる長期間有効な API トークンを発行します。管理者は設定 ▸ API トークンで発行します。生のトークン値は作成時にちょうど一度だけ表示され、保存されるのはそのハッシュだけです。

トークンは 5 つの要素で決まります。

使える入口。 MCP エンドポイントと REST API のどちらを認証できるか。この項目が存在する前に作られたトークンは mcp のみを持つため、アップグレードで既存の認証情報の権限が広がることはありません。REST を許すのは作成時の明示的な選択です。
所有者。 トークンが動作するアカウント。トークンは 2 つの軸のどちらでも所有者を超えられません。実効ロールはトークンのロールと所有者の現在のロールの低い方で、可視範囲も同じように所有者のものが上限になります。したがってアカウントを降格・限定すれば直ちにトークンも狭まり、無効化・削除すれば失効します。
ロール。 最小権限を選んでください。Viewer は読み取りをすべてカバーし、Operator ではアラートの確認と分析の実行が加わります。ロールによらずトークンにできないことが 2 つあります。ユーザー管理（自身の後継を発行できる認証情報は、元の失効を生き延びてしまいます）と、「サインイン中のアカウント」を意味するエンドポイントの利用です。
可視範囲（スコープ）。 トークンが参照できるノードグループ。アカウントが持つグループスコープと同じもので、どちらの入口でも尊重されます。未設定ならフリート全体です。
任意の有効期限。 省略すれば無期限で、連携を動かすサービスアカウントの認証情報にはそれが適切な答えです。

トークンは所有者を超えられないため、すでにスコープ付きのアカウントが所有するトークンは、そのアカウントのスコープを継承し、別のスコープを与えることはできません（400 owner_is_scoped）。これは通常望ましい封じ込めです — アカウントを絞れば、それが持つ認証情報すべてが即座に狭まり、再発行の必要もありません。トークンごとに異なる範囲を与えたい場合は、その範囲に限定したサービスアカウントをトークンごとに用意してください。

サービスアカウント

無人の認証情報は、個人に属するべきではありません。担当者が異動すれば連携も一緒に消えるからです。 サービスアカウント（設定 ▸ ユーザー ▸ ユーザーを追加、アカウント種別で サービスアカウント）はパスワードを持たない機械の識別子で、ローカルフォームでも SSO でもサインインできません。API トークンを所有するためのもので、トークンが人事異動を生き延び、 1 つのアカウントを無効化すればそれが所有する認証情報がまとめて止まります。

最後の管理者を削除させないガードは、人がサインインできるアカウントだけを数えます。そのためサービスアカウントが Admin ロールを持っても、唯一の管理者にはなりません。

アカウント表が更新されるのは SSO ログイン成功時だけなので、IdP がユーザーを無効化しても Yagra には通知されず、その行はただ更新されなくなります。セッションは 1 日以内に期限切れになるためこの盲点をやり過ごせますが、長寿命のトークンはそうではありません。そこで SSO アカウント が所有するトークンは、所有者がその期間サインインしないと停止します（YAGRA_PAT_OIDC_IDLE_DAYS、既定 30 日）。所有者の沈黙が唯一の手がかりだからです。ローカル/ サービスアカウントは対象外で、これも無人のトークンをサービスアカウントに持たせるべき理由です。

トークンの発行と失効はどちらも管理者の操作で、いずれも監査されます。トークンを使った MCP の書き込みは、そのトークンを名指しした監査エントリを毎回記録し、トークンは同じページからいつでも失効させられます。トークンの使い方は AI クライアントの接続を参照してください。

監査ログ

状態を変えるすべての操作 — 設定の作成や編集、アラートの確認、メンテナンスウィンドウの開始、ユーザーとトークンの管理、そしてすべてのログイン — は、追記専用の監査ログに記録されます。誰が、何を、いつしたか、です。MCP ツール経由の書き込みは WebUI 経由の書き込みと同じように監査されるため、Operator のトークンで動く AI アシスタントも、オペレーターと同じ足跡を残します。

管理者は設定 ▸ 監査ログで閲覧します。

公開ダッシュボードモード

Yagra は、読み取りを開放したステータス表示として動かせます。YAGRA_PUBLIC_DASHBOARD=true にすると読み取り API が認証なしで提供され、壁掛けボードや未認証のブラウザからダッシュボード、ノード状態、アラートを見られるようになります。

このモードが開くのは読み取りだけで、しかもその全部ではありません。

すべての書き込みには、引き続き認証済みのセッションと対応する権限が必要です — 匿名の閲覧者は見ることはできても、触ることはできません。
MCP は常にトークンを必要とします。 公開ダッシュボードが有効でも同じです。/mcp は絞り込みのかかっていない監視データを返すため、無条件に認証が必要なままです。
何を明かしてしまうかを理由に、閉じたままの読み取りもいくつかあります。たとえばしきい値のルール一式は、Yagra がいつ誰を呼び出すかを記述したものなので、その閲覧には設定管理の権限が必要で、匿名の閲覧者には公開されません。