ユーザー・ロール・SSO

Yagra は、最初のリリースからロールに基づくアクセス制御を持っています。

アカウントの作られ方は 3 通りあります。ローカルで作る、SSO で自動的に作られる、API トークンとして発行する、です。どの場合も、アカウントは 3 つのロールのどれかを持ちます。状態を変える操作はすべて権限を確かめられ、変えた事実はすべて監査ログに残ります。

このページでは、アクセス制御の全体を扱います。ロールと権限、ローカルアカウントとそのセッションの一生、シングルサインオン、API トークン、そして公開ダッシュボードモードとの関係です。

ロール

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

Viewer（閲覧者） — 読み取り専用。インベントリ、メトリクス、ダッシュボード、トポロジ、イベント、アラート。Viewer は WebUI が見せるものすべてを見られますが、何も変更できません。
Operator（オペレーター） — Viewer に加えて、監視そのものを動かせます。アラートの確認（ACK）やミュート、トラブルシュート分析と AI による根本原因説明の実行、メンテナンスウィンドウの開始と終了。さらに「何を監視するか」の決定 — ノード、グループ、プロファイル、しきい値、収集、探索、イベントルール、レポート — と、機器へ届くための認証情報の管理。オンコール担当のロールです。
Admin（管理者） — Operator に加えて、デプロイそのもの。データがどこへ送られるか、プロセスが何として動くか、誰がサインインできるか。通知の配信とルーティング、転送、TLS 証明書、アップグレード、データ保持、AI プロバイダ、設定バンドルとサポートバンドル、ポーラー台帳、ユーザー管理、そして監査ログ。

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

以前のリリースでロールを割り当てた方に、知っておいてほしい変更が 1 つあります。オペレーターが監視を動かせるようになりました（v0.2.10）。

ノードを 1 台足す、しきい値を編集する、探索を実行する、デバイスプロファイルを変える — これらはすべて管理者限定でした。1 つの権限「設定の管理」が、「何を監視するかを決める」と「デプロイを変える」の両方を兼ねていたからです。オペレーターはインシデントに対応できても、そのインシデントを上げた監視を設定できませんでした。

この権限を 2 つに割りました。「監視の管理」と「認証情報の管理」はオペレーター以上が持ちます。新設した**「デプロイの管理」は管理者限定**で、デプロイそのものを変えるもの・データが箱の外へ出るものを担当します。

アップグレードの前に、オペレーターのアカウントを確認してください。 できることが広がります。 Viewer と Admin は変わりません。

権限とグループスコープ

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

権限	何ができるか	Viewer	Operator	Admin
View	スコープ内のインベントリ・メトリクス・アラートの閲覧	✔	✔	✔
Respond to incidents	アラートの確認（ACK）やミュート、イベントアラートのクローズ、トラブルシュート分析の実行、AI による根本原因説明の依頼		✔	✔
Manage maintenance	メンテナンスウィンドウの開始と終了		✔	✔
Manage monitoring	何を監視し、いつアラートを上げるかの決定: ノード、グループ、プロファイル、しきい値、収集、探索、イベントルール、レポート		✔	✔
Manage credentials	監視用の認証情報の作成・編集・ローテーション		✔	✔
Manage the deployment	デプロイそのものと、データが箱の外へ出るものの変更: 通知の配信、転送、TLS 証明書、アップグレード、データ保持、AI プロバイダ、設定バンドル、サポートバンドル、ポーラー台帳			✔
Manage users	ユーザーアカウントとロール割当の管理			✔
View audit log	監査ログの閲覧（誰が何を変更したか）			✔

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

グループスコープ。 アカウントはロールとは別に、見える範囲も持ちます。すべてのグループか、指定したノードグループの集まりです。

この範囲は、そのアカウントがインベントリのどの部分に関わるのかを表します。どのグループにも属していないノードは、「すべてのグループ」を対象とする範囲の下にしか入りません。

API の読み取りは、呼び出した人のグループスコープで絞られます。ノードの一覧は許可されたグループとその配下だけになります。集計やランキングも同じ集合に絞られます。

範囲外のノードは 404 を返します。存在しない ID と同じ応答なので、ID を総当たりして探ることはできません。

1 台のノードを指定する書き込みも、同じ決まりに従います。範囲外のノードを消す・名前を変える・移す・プールを変えると 404 を返します。チェックや収集項目を足す場合も同じです。範囲外のフォルダへの移動も断ります。自分から見えない場所にノードを置けないようにするためです。

一部のエンドポイントには、ノード単位の帰属が残っていません（組み立て済みのレポート、集計済みのフリートの推移など）。そうしたものは、フリート全体の数値を黙って返す代わりに、範囲の限られた呼び出し元を拒否します。

書き込みのうち 2 系統は、同じ理由で範囲の限られたアカウントを丸ごと断ります。資格情報は、どのグループにも属しません——1 本のコミュニティ文字列、1 本の API キーで、すべての拠点をポーリングしているからです。ですから作成・変更・削除は 403 を返します。一覧の読み取りは今まで通り答えます。ノードのダイアログや Discovery の資格情報の選択欄がそれを必要とするからで、範囲の限られたオペレーターも、既存の資格情報を自分のノードに結び付けることはできます。Cisco Meraki に対する書き込みも、同じように断ります。組織は丸ごと監視するものであり、そのキーは組織内のすべてのデバイスを見られますし、まだ取り込んでいないデバイスはどのグループにも属していないからです。

範囲の割り当て方。 設定 ▸ ユーザーの行の操作から可視範囲を変更を選び、グループにチェックを入れます。1 つもチェックしなければ、フリート全体に戻ります。

アカウントは、制限の無い状態から始まります。SSO のアカウントも同じで、初回サインインで作られてからここで絞ります。割り当てた内容は、以後のログインでも保たれます。これは Yagra 側で決めたことであり、ディレクトリから毎回導き直すものではないからです。

使う前に知っておくべき決まりが 2 つあります。

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

範囲を保存すると、そのアカウントの今のセッションはサインアウトされます。理由はロールを変えたときと同じです。範囲はセッショントークンに書き込まれているので、生きているトークンは古い広い範囲を持ち続けてしまいます。

サインイン中のアカウントが制限されている場合、アカウントメニューにその旨が出ます。範囲を絞られた担当者から見ると、一覧が短くなるだけだからです。「3 拠点が見えている」のか「3 拠点しか無い」のかを区別する手がかりが、他にありません。

ローカルアカウント

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

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

それでサインインし、そのあと変更してください。

ローカルアカウントの管理は、設定 ▸ ユーザーで行います。ここでできるのは、ロールを指定したアカウントの作成、パスワードの変更とリセット（“Change password”）、アカウントの無効化、削除です。

自分のパスワードを変える。 これに管理者は要りません。右上のアカウントバッジに、環境設定とログアウトのあいだにパスワードの変更があります。新しいパスワードだけでなく現在のパスワードも訊かれるので、セッションを盗まれてもアカウントごと持っていかれることはありません。

LDAP や IdP 経由でサインインするアカウントには、この項目は出ません。Yagra がパスワードを持っていないからです。そのかわり、バッジがパスワードの在り処を伝えます。

セッションの一生。 ログインすると、Bearer のセッショントークンが発行され、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 トークン

人が操作しないクライアントのために、Yagra は長期間使える API トークンを発行します。トークンは yat_ で始まります。使う相手は、MCP でつなぐ AI アシスタント、スクリプト、CI のジョブなどです。

発行は管理者が設定 ▸ API トークンで行います。生のトークンの値が表示されるのは、作成時の ちょうど 1 回だけです。保存されるのはハッシュだけです。

トークンの性質は、次の 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 日）。所有者が黙っていることが、唯一の手がかりだからです。

ローカルのアカウントとサービスアカウントは、この対象外です。これも、人が見ていないトークンをサービスアカウントに持たせるべき理由の 1 つです。

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

監査ログ

状態を変える操作は、すべて追記だけの監査ログに残ります。設定の作成と編集、アラートの確認、メンテナンスウィンドウの開始、ユーザーとトークンの管理、そしてすべてのログインです。自分の WebUI の設定（閉じたフォルダや列の幅）の保存は記録しません。本人の画面しか変えないからです。

記録されるのは、誰が、何を、いつしたかです。MCP ツール経由の書き込みも、WebUI 経由の書き込みと同じように監査されます。ですから Operator のトークンで動く AI アシスタントも、人と同じ足跡を残します。

管理者は、設定 ▸ 監査ログで見られます。

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

Yagra は、アカウントを持たない訪問者に 1 枚のボードだけを見せられます。ログイン不要の閲覧は、管理者が 設定 ▸ サインイン方法 ▸ 公開ダッシュボードで入れる設定で、既定は OFF です。外に出るのは ダッシュボード ▸ 公開ダッシュボードで組んだボードであり、読み取り API 全体ではありません。

このボードを組むのに必要なのは管理者（manage_system）で、共有ボードの manage_config より一段上です。ここに何を載せるかが「見知らぬ相手が何を読めるか」を決めるからです。

このモードが開くのは読み取りだけで、しかもそのボードが必要とするぶんだけです。

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

匿名の訪問者が着くのは、このサインイン画面で、ボードではありません。ボードを公開していると、サインイン画面に公開ダッシュボードを表示ボタンが出て、そこから入れます。公開デプロイでも、運用者にははっきりした入口が残ります。