> Source: https://clickhouse.github.io/loom/ja/operations/sso/ (Markdown: https://clickhouse.github.io/loom/ja/operations/sso.md)

<!-- i18n: source=docs/operations/sso.md blob=43ac40cca373fa5c10d8d54eab80809979c4b157 model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://clickhouse.github.io/loom/operations/sso/)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/operations/sso/), which is authoritative.

<a id="single-sign-on-oidc"></a>

# シングルサインオン（OIDC）

Loom は、人間のサインインを OpenID Connect の ID プロバイダーに任せることができます。有効にすると、ダッシュボードには **Sign in with SSO** ボタンが 1 つ表示され、`loom login` と `loom.login()` はプロバイダー経由で承認され、OAuth で接続する MCP クライアントもそこでサインインします。また、Loom はパスワードによるサインインとセルフサインアップを拒否します。トークンは引き続き Loom 自身が発行し、プロバイダーはユーザーが誰であるかを保証するだけです。デフォルトでは無効で、新規インストールではパスワードでサインインします。

<a id="how-sign-in-works-without-sso"></a>

## SSO を使わない場合のサインインの仕組み

認証を有効にすると（`LOOM_AUTH_REQUIRED=true`）、`loom login` は追加の設定なしで動作します。URL とコードが表示されるので、ユーザーは任意のブラウザーでその URL を開き、Loom のパスワードでサインインして承認します。設定が必要な項目はありません。詳細は[トークンとグラント](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md#sign-in-from-a-terminal-or-a-notebook)を参照してください。

<a id="okta-setup"></a>

## Okta のセットアップ

1. Okta の管理コンソールで、**Applications → Create App Integration → OIDC → Web Application** を選択します。
2. **Grant types:** Authorization Code と Refresh Token を選択します。refresh token の動作では **Rotate token after every use** を選びます。
3. **Sign-in redirect URI:** `<public Loom URL>/oauth/callback` を正確に指定します（例：`https://loom.example.com/oauth/callback`）。サインアウト用のリダイレクトは不要です。
4. **Assignments:** Loom へのアクセスを許可するユーザーまたはグループを指定します。
5. クライアント ID とシークレットをコピーし、次のように設定します。

```bash
LOOM_OAUTH_LOGIN_PROVIDER=oidc
LOOM_OAUTH_ISSUER=https://loom.example.com      # Loom's public URL, as in step 3
LOOM_OIDC_ISSUER=https://your-org.okta.com      # or https://your-org.okta.com/oauth2/default
LOOM_OIDC_CLIENT_ID=0oa…
LOOM_OIDC_CLIENT_SECRET=…
```

これらのいずれかが欠けていると、Loom は起動を拒否します。org 認可サーバーで十分です。Loom が読み取るのは ID トークンの標準クレームのみです。

<a id="scopes-and-claims"></a>

### スコープとクレーム

Loom は `openid email profile` を要求します。プロバイダーの discovery ドキュメントに `offline_access` が記載されている場合（Okta は記載しています）は、それも要求します。必要になるものは次のとおりです。

- `email_verified: true` を伴う `email`：アカウントのキーとして使用します。検証済みのメールアドレスがないサインインは拒否されます。
- Okta の refresh token（`offline_access` から取得）：Loom が更新を行うたびに（最大でも 1 時間おき）、まず Okta に対してこのトークンを使用します。そのため、Okta で無効化されたユーザーや、**End all sessions** でサインアウトされたユーザーは、次の更新時に Loom を利用できなくなります。refresh token を発行しないプロバイダーには、Loom の refresh token も発行されません。その場合、セッションは 1 時間有効なアクセストークンの期限切れとともに終了します。

グループクレームはマッピングされません。名前空間へのアクセスは、Loom 独自の権限付与によって決まります。

Loom は、discovery ドキュメントの `id_token_signing_alg_values_supported` に記載されたアルゴリズムのうち、RS256、RS384、RS512、PS256、ES256、ES384、ES512 のいずれかで ID トークンの署名を検証します。何も記載がない場合は RS256 のみを使用します。ドキュメントに記載のないアルゴリズムで署名されたトークンは拒否されます。`none` や HMAC アルゴリズム（`HS256` など）のトークンも、ドキュメントの記載にかかわらず拒否されます。これらしか記載していないプロバイダーでは、誰もサインインできません。

<a id="accounts"></a>

## アカウント

検証済みのメールアドレスは、連絡先メールアドレスによって SSO アカウント（パスワードを持たないアカウント）と照合されます。パスワードアカウントは、そのメールアドレスにリンクされた後にのみ照合されます。セルフサインアップはメールアドレスを検証せずに受け付けていたため、メールアドレスの一致だけで照合すると、そのアドレスを最初に入力した人にアカウントを渡してしまうからです。リンクされたアカウントは、サブジェクト、グラント、名前空間、データをそのまま保持し、新しいアカウントは作成されません。

- **SSO を有効にした直後**に、所属する人々のアカウントをまとめてリンクします。`loom sso adopt --domain example.com` は、そのドメインのパスワードアカウントを所有者とともに一覧表示し、`--apply` でそれらをリンクします（SSO が無効の間は実行を拒否します。パスワードでのサインインが可能なままだと、後述の失効をすり抜けてしまうためです）。このコマンドは実行場所の設定を読み込むので、サーバーと同じ設定で（サーバーのコンテナ内、または同じ環境変数を付けて）実行するか、稼働中のサーバーが応答する `/v1/admin/sso.adopt` を呼び出してください。このコマンドは、そのドメインのアドレスがプロバイダー側の人物のものであることを保証する操作なので、一覧をよく確認してください。他の人が登録したアドレスもリンクされ、リンクすると、そのアドレスのもとに書かれたすべてのグラントがそのアカウントを許可するようになります。アカウントが複数の組織にまたがるメールアドレス、所有者が複数いるメールアドレス、SSO がすでに到達できるメールアドレスはスキップされます。adopt は、対象となったサブジェクトが保持するすべてのトークンを失効させるため、ユーザーは再度サインインする必要があります。これには、セッションから作成したサービスアカウントや MCP のトークンも含まれ、それらを使っている CI は、専用のボットを用意するまで動作しなくなります（下記参照）。`--keep-tokens` を指定するとトークンは維持されますが、不正に先取りした人が作成したトークンも残ります。そのドメインでパスワード登録されたボットも一覧に含まれます。`--skip <its email>`（繰り返し指定可）で除外すると、`loom bot` に移行するまで、使用中のトークンが保持されます。リンクされていないアカウントに一致しない `--skip` があると、実行全体が拒否されるため、タイプミスでボットが adopt されることはありません。
- **adopt されなかった人**には、最初の SSO サインイン時に、アカウントの Loom パスワードを一度だけ求めます。入力するとリンクされます。誤ったパスワードは通常のサインイン制限に数えられます。
- 別のアドレス（個人用のアドレスや `+tag` 付きのアドレス）で登録されたアカウントは、そのドメインに属さないか、プロバイダーが検証するアドレスと異なります。`loom sso link --email <their provider address> --org <org> --namespace <ns>` でアカウントを確認でき、`--apply` でそのアドレスを連絡先にしてリンクします。これにより、次回の SSO サインインでは、サブジェクト、グラント、データ、トークンを保持したままそのアカウントに入ります（失効されるものはありません）。adopt と同様に SSO が有効である必要があります。セルフサインアップが閉じていれば、解放されたアドレスを誰かが登録して、それが指していたものを引き継ぐことはできません。古いアドレスのリンクは削除され、そのアドレスのもとで失効済みだったグラントは、失効した状態のままアカウントのサブジェクトに引き継がれるので、引き続きその人のトークンの上限として働きます。古いアドレスに有効なグラントが残っている場合（古いアドレスがリンクされているときは、アカウントのサブジェクトにグラントしてから失効させてください。未検証だったときは、そのグラントは誰も許可しないので、そのアカウント向けだったならアカウントのサブジェクトにグラントしたうえで失効させてください）や、参加リクエストが保留中の場合（却下してください）は、実行を拒否します。古いアドレスが別のアカウントの検証済みメールアドレスである場合、そのグラントとリクエストはそのアカウントのものなので、リンクはそれらに触れず、アカウントのトークンを制限していたときと同様に、それぞれを失効した状態でアカウントのサブジェクトに引き継ぎます。また、別のアカウントがすでにそのアドレスを名乗っている場合も拒否します。それが以前の SSO サインインで作られた JIT アカウントであるときは、先に `loom claim-release` で解放してください。そのメモリは JIT アカウントに残り（`namespace.snapshot` と `namespace.restore` で移せます）、そのアカウントに対して作られたグラントは作り直す必要があります。
- `loom sso unlink --email <email> --apply` はリンクを取り消します。アドレスのもとに保存されたグラント（リンク前に書かれたもの）は、そのアカウントを許可しなくなります。リンク中に作られたグラントはログインハンドルのもとに保存されているので残ります。それらは `grants.revoke` で失効させてください。すでに開いているセッションは終了しません。`loom revoke-token --subject` で失効させてください。
- 自分のアドレスを名乗るパスワードアカウントは自分のものではないと主張する人は、そのアカウントが `LOOM_OIDC_JIT_ORG` にある場合は拒否され、`auth.sso_link_declined` が監査ログに記録されます。そのアカウントが残っていると、そのアドレスでのパスワードサインインは引き続きそれを見つけてしまい、アドレスの失効は両方のアカウントに及びます。他の人が登録したアドレスを解放するには、そのアカウントを `loom claim-release` で解放します。これによりメールアドレスとリンクが消去され、`LOOM_OIDC_JIT_PROVISION=true` であれば、その人の次回のサインインで本人のアカウントが作られます。別の組織にあるアカウントは、それを妨げません。そのアドレスを名乗る失効済みのアカウントは、同一人物かもしれないため、新しいアカウントの作成をブロックします。

アカウントを持たない人については次のとおりです。

- `LOOM_OIDC_JIT_PROVISION=true` にすると、最初のサインイン時にアカウントが作成されます。`LOOM_OIDC_JIT_ORG` 内にその人が admin となる個人用の名前空間が作られ、そのセッションにはロール `writer` が付きます。
- `LOOM_OIDC_JIT_EMAIL_DOMAINS=example.com,example.org` を設定すると、作成対象がそれらのドメインに限定されます。それ以外の人には「sign-in denied」と表示され、`loom login` はエラーで停止します。
- JIT が無効の場合は、既存のアカウントのみサインインできます。
- JIT アカウントの名前空間は `u-<name>-<8 hex>` で、名前はメールアドレスから付けられます。JIT が有効な間は、他の人がこの形式の名前空間を作成することはできません。JIT を有効にする前に誰かが作った名前はその人のものとして残り、新しい人には次に空いている名前（`-2`、`-3`、その後はランダムな接尾辞）が付きます。

プラットフォーム管理者は、`LOOM_PLATFORM_ADMINS` に列挙された検証済みメールアドレスの人です。プロバイダーが管理者権限を付与することはできません。

<a id="bots-and-ci"></a>

## ボットと CI

ボットはプロバイダーにサインインすることはなく、長期間有効なシークレットも保持すべきではありません。ボットのデータが属する名前空間（通常は、管理者が複数いるチーム名前空間を、1 つの org の中で最初に登録したもの）とともに登録します。ボットのトークンは `sa:<name>` 向けで、有効期間は 1 時間、またはボットの上限がそれより短い場合はその上限です。ただし、リクエストでその上限までの別の有効期間を求めた場合はそれに従います（後述）。ボットの書き込みには `actor=process:sa:<name>` が付与されます。

- **鍵。** Loom は公開鍵の側だけを保持し、ボットはトークンごとに短いアサーションに署名します（`private_key_jwt` による OAuth クライアント資格情報）。

  ```bash
  loom bot create --name triage-bot --org acme --namespace-role triage=writer \
    --generate-key ./triage-bot.pem
  # on the bot, with `pip install clickhouse-loom[machine]`:
  LOOM_CLIENT_ID=triage-bot LOOM_CLIENT_KEY_FILE=./triage-bot.pem python agent.py
  ```

  鍵は次のいずれかから読み込まれます。`LOOM_CLIENT_KEY_FILE`（PEM ファイル）、`LOOM_CLIENT_KEY`（PEM そのもの。シークレットマネージャーが環境変数に注入する形式）、`LOOM_CLIENT_KEY_SECRET`（PEM を保持する AWS Secrets Manager のシークレット ID または ARN。`pip install clickhouse-loom[aws]`）。SDK はトークンごとに鍵を読み直すため、その場でローテーションした鍵も反映されます。TypeScript SDK（`@clickhouse/loom`）も同じ変数を使います。それ以外のクライアントは、アサーションに自分で署名します（RFC 7523：`iss` と `sub` はボットの名前、`aud` は `/.well-known/oauth-authorization-server` の `token_endpoint`、`exp` は 2 分後、`jti` は新しい値）。

- **CI ジョブ。** シークレットは一切不要です。ジョブは、CI プラットフォームがその実行用に発行する OIDC トークンを渡します。Loom は、その発行者から、その audience で、すべての `--claim` が一致する場合にのみ受け付けます（`*` で終わる値は前方一致）。プラットフォーム上のどのジョブでも任意の audience のトークンを取得できるため、クレームでリポジトリとブランチを指定してください。

  ```bash
  loom bot create --name deploy --org acme --namespace-role deploys=writer \
    --issuer https://token.actions.githubusercontent.com --audience loom \
    --claim repository=acme/app --claim ref=refs/heads/main
  # in the job (it needs permission to request its OIDC token):
  LOOM_CLIENT_ID=deploy LOOM_WORKLOAD_AUDIENCE=loom python deploy.py
  ```

  ジョブにトークンを渡す方式のプラットフォームでは、そのトークンを `LOOM_WORKLOAD_TOKEN`（または `LOOM_WORKLOAD_TOKEN_FILE` で指定したファイル）に置きます。ジョブ内のすべてのクライアントは、トークンが有効な間、必要なだけ何度でもそれを交換でき、Loom のトークンがそのトークンより長く有効になることはありません。

- **多数のエージェント、1 つの信頼。** エージェントごとに個別の OIDC トークンを発行するコントロールプレーンは、それらすべてに対して 1 つの信頼を登録します。`--agent-claim` は、トークンがどのエージェント向けかを示すクレームを指定します（英字、数字、`-`）。各エージェントにはサブジェクト `sa:<trust>:<agent>` と、その信頼の org 内の専用名前空間 `<trust>-<agent>` が割り当てられ、名前空間は最初の交換時に作成されます。`--namespace-role` は、各エージェントが自身の名前空間に加えて共有するものです。信頼は、自身が作成していない名前空間には到達せず、クレームが org を選ぶこともありません。人間がエージェントのメモリにアクセスするには、他の名前空間と同様に、管理者が権限を付与します。

  ```bash
  loom bot create --name fleet --org acme --issuer https://issuer.example \
    --audience loom --claim tenant_id=acme-prod --agent-claim agent_id \
    --jwks-uri https://keys.issuer.example/jwks.json
  # on each agent: its token in a file, renewed by the control plane
  LOOM_CLIENT_ID=fleet LOOM_WORKLOAD_TOKEN_FILE=/run/agent/oidc-token python agent.py
  ```

  同じ信頼に属するエージェントは、別のエージェントに自分のメモリを一方向で読ませることができます。これを決めるのはコントロールプレーンで、貸し出す側のエージェントとして（そのエージェントのトークンで）呼び出します。

  ```bash
  curl -s -X POST "$LOOM_BASE_URL/v1/grants.share_agent" -H "Authorization: Bearer $A_TOKEN" \
    -d '{"org":"acme","namespace":"fleet-a","grantee":"b","role":"viewer"}'
  ```

  エージェント `b` の次のトークンには `fleet-a` が viewer として含まれます（別のサーバーで発行される場合は `LOOM_GRANT_CACHE_TTL_SECONDS` 以内）。`a` は `b` のものを何も得られません。`role` は `viewer` または `writer` です。エージェントが共有できるのは自身の名前空間だけで、相手も同じ信頼のエージェントに限られ、名前空間が制限されている間は共有できません（それ以前に行われた共有は、取り消されるまで残ります）（[`grants.share_agent`](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/grants.md#grantsshare_agent)）。共有によって、`b` が持つ権限が下がることも、他者が作成した権限が上書きされることもありません（409）。自分の共有を下げるには、エージェントがいったん取り消してから共有し直します。同じボディ（`role` なし）で [`grants.unshare_agent`](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/grants.md#grantsunshare_agent) を呼ぶと、そのエージェントが貸し出したものを取り戻せます。`b` は、そのサーバーでは即座に、他のサーバーでは `LOOM_GRANT_CACHE_TTL_SECONDS` 以内に拒否されます。管理者が作成した権限は残ります（409）。名前空間の管理者は、`grants.create` と `grants.revoke` で `sa:fleet:b` に権限を付与または取り消せます。エージェントのトークンは、そのサブジェクトが org 内で持つあらゆる権限を、最大でも writer として取り込みます。貸し出された名前空間は、トークンにその名前で記載されます。ただし、そのエージェント自身のものと信頼の共有分を含むすべての名前空間が、トークンの 4,096 バイトに収まる場合に限られます（最長の名前で 15 個、短い名前ならそれ以上）。これにより、プロキシの 8 KB ヘッダー上限を下回ります。これを超える共有は拒否され、トークンがすでに記載しているロールを引き上げるだけの共有は拒否されません（2 つの共有が同時に行われると上限を超えることがあり、その場合トークンには収まる分だけが記載されます）。信頼の共有名前空間は、63 文字のエージェント自身の名前空間分の余地を含めて、この 4,096 バイトに収まる必要があり、収まらない場合は `loom bot create` が拒否します。

  `tenant_id` を完全一致で指定すると、1 つの信頼は 1 つのテナントに限定され、各テナントのエージェントはそれぞれの org に入ります（`sub` の前方一致を追加条件として加えてもかまいませんが、唯一の条件にしてはいけません）。`--jwks-uri` は、Loom から発行者のディスカバリードキュメントに到達できない場合に、発行者が鍵を公開している場所を指定します。数分しか有効でないトークンでも問題ありません。Loom のトークンはそれより長く有効になることはなく、SDK とコーディングエージェントのプラグインは、期限切れの前に更新します（後述）。エージェント自身がトークンを保持する代わりに、その前段のプロキシが同じ交換を行い、`Authorization` ヘッダーを自分で追加することもできます。交換では `client_id` を省略できます（RFC 8693 では必須ではありません）。その場合、Loom は、トークンの発行者が持つ有効な信頼のうち、audience とクレームが一致する 1 つを採用し、どれにも一致しない、または複数に一致するトークンは拒否します。

  信頼を無効にすると、すべてのエージェントのトークンが終了します。`loom revoke-token --subject sa:fleet:<agent>` は 1 つのエージェントのトークンを終了し、`loom claim-release` はその名前空間を完全に解放します（以後そのエージェントは拒否されます）。コントロールプレーンが廃止したエージェントの名前空間とデータは、解放または消去するまで残ります。

  エージェントの名前空間は、最初の交換時に作成されます。それ以前にエージェントに何かを付与したい場合（たとえば、コントロールプレーンがエージェント作成時にアタッチする名前空間など）は、プラットフォーム管理者が事前に作成します。`loom call /v1/admin/bots.provision_agent --data '{"name":"fleet","agent":"a"}'` は、その交換と同じように `fleet-a` を作成し（信頼の印が付き、エージェントが唯一のオーナーとなり、`--max-agents` に数えられます）、その org、名前空間、サブジェクト（`sa:fleet:a`）を返します。`auth.agent_provisioned` が管理者を actor として監査に記録され、信頼が拒否する名前空間は作成されず、繰り返し実行しても何も変わりません。エージェントの最初の交換では、その名前空間が自身のものとして採用されます。

  すべての信頼は、受け入れる範囲に上限を持ちます。ワークロードトークンの有効期間が `--max-token-age` 秒（exp − iat、デフォルトは 3600）を超えると拒否されます。エージェントの信頼が保持できる有効なエージェントは最大 `--max-agents` 件です（デフォルトは 1000。解放されたエージェントの名前空間は枠を返しますが、その名前が再び作成されることはありません）。また、信頼には、`iss`、`aud`、`exp`、`iat`、`nbf`、`jti` のほかに、完全一致の値を持つクレームが 1 つ必要です（これらは、発行者が Loom 向けに署名するすべてのトークンに含まれます）。1 つのトークンが該当しうる同一発行者の 2 つの信頼のうち、一方がエージェントを区別する場合は、登録時に拒否されます。クライアントを指定しない交換では、どちらも採用できないためです。署名アルゴリズムは、公開された各鍵の種類に従います（RS256 または ES256）。

  交換は、すべてのレプリカをまたいで 10 分あたりの回数が制限されます。1 つの信頼につき 50,000 回（`LOOM_WORKLOAD_EXCHANGES_PER_TRUST`）で、エージェントクレームを持つ信頼では、1 つのエージェントにつき 300 回（`LOOM_WORKLOAD_EXCHANGES_PER_AGENT`）です。エージェントのない信頼は 1 つのワークロードとみなされ、信頼の上限だけが適用されます。リポジトリのすべてのジョブが 1 つの `sub` を共有するためです。上限を超えると `/oauth/token` は 429 を返し、SDK とプラグインは保持しているトークンを使い続けて 30 秒後に再試行します。カウントされるのは発行者が署名したトークンだけなので、発行者の鍵を持たない者が信頼の枠を使い切ることはできず、自身の上限で拒否されたエージェントが信頼の枠を消費することもありません。エージェントが頻繁に更新するフリートでは、信頼の上限を引き上げてください。SDK とプラグインは、トークンの期限の 5 分前、または有効期間の半分が先に来る場合はその時点で更新します。SDK はプロセスごとに更新し、プラグインはエージェントのホームごと、かつ新しいワークロードトークンごとに 1 回更新します（同時に起動するフックは、それぞれが更新することがあります）。更新のたびに新しいワークロードトークンが提示される場合、1 時間のトークンは 55 分後に、5 分のトークンは 2.5 分ごとに更新され、10 分あたり 4 回の交換になります。Loom のトークンはワークロードトークンの残り時間しか有効ではないため、プラットフォームが有効期間の途中で置き換える、あるいは一切置き換えないトークンは、より頻繁に更新されます。4 分ごとに置き換えられる 5 分のトークンは、置き換えごとに約 3 回の更新に落ち着き、10 分あたり平均 7.5 回の交換になります（10 分間のウィンドウでは最大 9 回）。置き換えられないトークンは、最後の 5 分間でさらに頻繁に更新されます。

  新しいエージェントの急増は、発行者の鍵の漏えいやコントロールプレーンの暴走の兆候であり、上限に達した信頼はすべての新しいエージェントを拒否します。`loom.auth.agents_provisioned` と `loom.auth.trust_agents_used_ratio` にアラートを設定してください（[アラート対象](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md#what-to-alert-on)）。

- **トークンの有効期間。** 指定がなければ、トークンの有効期間は 1 時間、またはボットの上限がそれより短い場合はその上限です。`--max-access-token-ttl SECONDS`（60〜86,400。`/v1/admin/bots.create` では `"max_access_token_s"`。`/v1/admin/bots.list` に表示され、1 時間以外の場合は `loom bot list` にも表示されます）で登録されたボットは、`/oauth/token` へのリクエストで、他のフォームフィールドとともに `expires_in=<seconds>` を指定すると、より長いトークンを得られます。求めた値が上限まで適用され（超えた分は拒否されず上限に切り詰められます）、レスポンスの `expires_in` に実際の値が示されます。上限が 1 時間未満の場合は、デフォルトも短くなります。CI やエージェントのトークンが、渡されたワークロードトークンより長く有効になることはありません。したがって、1 日有効のトークンを望むコントロールプレーンは、1 日有効なワークロードトークンを、それを許容する `--max-token-age` を持つ信頼で渡します。整数秒でない、または 60 未満の `expires_in` は、証明が消費・カウントされる前に `invalid_request` で拒否されます。

  1 時間以外の上限は、すべてのレプリカがそれに対応したサーバー（マイグレーション 77）を実行するまで、また、実行中のサーバーがまだ `loom.instances` に登録されていない間は、拒否されます。古いサーバーは `expires_in` と上限を無視して 1 時間のトークンを発行し、ボットを保存するときに上限を 3600 にリセットします。そのようなサーバーにロールバックすると、すべてのボットのトークンは再び 1 時間になり、保存のたびに上限もリセットされます。新しいサーバーが再び稼働したら、`loom bot create --replace` に、登録済みのボットの鍵または信頼とロール、および `--max-access-token-ttl` を指定して、もう一度適用してください。ボットを置き換えると、そのボットが保持するトークンも終了します。

  長いトークンでも、終了させる難しさは変わりません。ボットの無効化または置き換え、`--expires-at` なしの `loom revoke-token --subject`、`/v1/admin/revoke_subject`（`issued_before` の有無を問わない）、`loom claim-release` は、有効期限にかかわらずそのトークンを即座に拒否し、`/oauth/revoke` は 1 つのトークンの失効を、そのトークンの期限まで保持します。ボットのトークン自身の期限より早い `--expires-at` では、失効が切れた時点でそのトークンが再び通るようになります。トークンに記載される内容は発行時に読み取られます。後から行われた共有や権限付与は、エージェントの次のトークンで反映されます（1 日有効のトークンでは最大 1 日後）。一方、取り消しはそれを待ちません。名前空間の削除（`namespace.delete`）は、`loom claim-release` とは異なり、その名前空間を含むボットのトークンを終了させません。トークンは期限が切れるまでアクセス権を保持し、それを許可するボットでは最大 1 日続くため、即座に終了させるにはボットを置き換えるか無効にするか、そのサブジェクトを失効させてください。また、発行者の署名鍵をローテーションしても、古いトークンと交換済みの Loom トークンは終了しません。期限が切れるまで有効なので、即座に終了させるには信頼を置き換えるか無効にしてください。

- `loom bot list` でボットを一覧表示できます。`loom bot disable --name …` は以後のすべての証明を拒否し、ボットが保持するトークンを失効させます。`loom bot create --replace`（新しい鍵、少ないロール）もトークンを失効させます。プラットフォーム管理者は、どこからでも `loom call /v1/admin/bots.create --data '{…}'`（`"generate_key": true` を指定すると、レスポンスに秘密鍵が 1 度だけ含まれ、保存が完了していない可能性がある場合にリクエストを再送するよう促す `warning` も付きます）、`/v1/admin/bots.list`、`/v1/admin/bots.disable` で同じことができます。`/v1/admin/sso.adopt`、`sso.link`、`sso.unlink`、`sso.password_link` は `loom sso` に対応します。
- ボットの置き換えまたは無効化は、次の秒に 5 秒を加えた時点までのトークンを失効させ、どちらもその待ち時間（約 6 秒）が経過してから戻ります。レプリカ間の時計のずれは 5 秒以内に収める必要があります（NTP で可能です）。進んでいるレプリカは、古いボットから存続するトークンを発行する可能性があり、遅れているレプリカは、時計がカットオフを過ぎるまで新しい鍵を拒否します。

静的な鍵しか保持できないソフトウェアには、オペレーターが発行するトークンを使います。有効期限付き（`--ttl-days 90`、スケジュールに沿って再発行）、または期限なし（`loom revoke-token` まで有効）です。

```bash
loom mint-token --subject sa:legacy --org acme --service-account \
  --namespace-role legacy=writer --json
```

Loom 自体を管理するシステム、たとえばテナントのために信頼や権限を登録するコントロールプレーンは、ボットとして `platform_admin` ロールを保持します。**プラットフォーム管理者はすべての org にまたがります**。このロールを持つトークンはすべての管理ルートを通過し、任意の org で動作できるため、付与する ID はできるだけ少なくし、鍵よりも信頼（漏えいするシークレットがない）を優先してください。`--platform-admin` でこのようなボットを登録します。`--namespace-role` は指定できず（トークンはすべての名前空間を対象とします）、`--agent-claim` も指定できず（単一の ID であり、エージェントではありません）、`--claim` は完全一致の値のみ使えます（前方一致では、一致するすべてのトークンにこのロールを与えてしまうためです）。他の信頼向けのトークンが一致しないよう、専用の audience を設定してください。

```bash
loom bot create --name controlplane --org acme --platform-admin \
  --issuer https://cp.example/workload-identity --audience loom-admin \
  --claim sub=controlplane
```

各証明に対して、このロールを持つ `sa:controlplane` 向けのトークンが発行され、リクエストできる有効期間と上限は、他のボットと同じです。リクエストがなければ 1 時間、またはボットの上限がそれより短い場合はその上限です。`loom bot disable` は、他のボットと同様にこのボットも終了させます。このフラグを設定できるのは、プラットフォーム管理者として Loom にサインインしている人（`/v1/admin/bots.create` の `"platform_admin": true`）か、ホスト上のオペレーターだけです。ルートは、プラットフォーム管理者ボットを含むすべてのサービスアカウントのトークンと、サードパーティ MCP クライアントのセッション（そのトークンはセッションとともに終了します）に対してこれを拒否するため、漏えいしたトークンが自分の永続的な後継を作成することはありません。`auth.machine_created` の監査行にこれが記録され、`loom bot list` と `/v1/admin/bots.list` にも表示されます。エージェントを区別する同一発行者の信頼が、プラットフォーム管理者の信頼のトークンを採用できてはいけません。それぞれに、相手のトークンが満たせないクレームを設定してください。たとえば、異なる `sub` の値を使います（こちらは `sub=controlplane`、テナント側は完全一致の `tenant_id` に加えて `sub=tenants/<id>/agents/*`）。そうしないと、2 つ目の登録は拒否されます。信頼を使えない場合は、オペレーターがサービスアカウント向けに、期限付きのプラットフォーム管理者トークンを発行します。`--platform-admin` は、`--ttl-days` のないトークン、または 90 日を超えるトークンを拒否し、エージェントのサブジェクト（`sa:<trust>:<agent>`）も拒否し、発行のたびに `auth.platform_admin_minted` の監査行を記録します。

```bash
loom mint-token --platform-admin --subject sa:controlplane --org acme --ttl-days 30 --json
```

管理者用のマシントークンは、稼働中のすべてのレプリカが人間のサインイン変更を保護するようになってから発行されます。古いレプリカがある場合や、フリートを読み取れない場合、交換は 503 `temporarily_unavailable` で拒否されます。CLI も最新のフリートビューを読み取り、同様に発行を拒否します。どちらのチェックも、ClickHouse を共有するデプロイ済みのプロセスとデプロイ外のプロセスの両方を対象とします。レプリカキャッシュはこれらの種類を区別するため、どちらのチェックでも使用しません。CLI は稼働中のレプリカが少なくとも 1 つ必要であり、空のフリートに対してトークンを発行できません。古いビルドへロールバックする前に、管理者ボットを無効化し、CLI が単体で発行した管理者のサブジェクトまたはトークンをすべて失効させてください。これは、そのビルドが稼働を始める前に行います。

SSO はボットや発行済みトークンには影響しません。`loom login` またはダッシュボードの SSO セッション（`/v1/me/service_accounts`）から個人が作成したトークンは、その人が選んだ期間だけ有効で、その人に帰属します。その人を失効させると、トークンも無効になります。サードパーティの MCP クライアントのセッションが作成したトークンは、そのセッションの終了とともに無効になります。長時間稼働するボットは上記のいずれかを使うため、誰かの退職によって停止することはありません。

<a id="sessions-and-logout"></a>

## セッションとログアウト

- ダッシュボードの SSO トークンの有効期間は 1 時間です。その後、ユーザーがもう一度ボタンをクリックします。Okta 自身のセッションが残っていれば、通常はこのクリック 1 回で済みます。
- `loom logout` は、サーバー上の Loom セッションと、Okta 上の Okta リフレッシュトークンを失効させます。
- 使用済みのリフレッシュトークンが再び送られてきた場合は、別の誰かがそのコピーを持っている可能性があります（またはクライアントがリフレッシュの応答を受け取れなかった可能性があります）。Loom はそのセッションを終了し、本人は再度サインインします。`loom login` またはダッシュボードの SSO セッションから発行されたサービスアカウントと MCP トークンは影響を受けません。盗難が疑われる場合は、これらを確認し（`loom call /v1/me/service_accounts`）、見覚えのないものを失効させてください。サードパーティの MCP クライアントのセッションが発行したものは、そのセッションとともに終了します。
- リフレッシュ時に Okta がユーザーを拒否した場合、そのセッションは終了します。
- `loom login` またはダッシュボードの SSO セッションから本人が作成したサービスアカウントと MCP トークンは、`loom logout` を含め、セッションが終了しても、本人が指定した期間だけ有効なままです（空欄は 90 日、0 は無期限）。作成したトークンはすべて本人のトークン一覧に保存されるため、本人から見えないものがセッションより長く残ることはありません。サードパーティの MCP クライアントのセッションは、セッションより長く残るトークンを発行しません。プロバイダー側でユーザーを無効化すると、そのユーザーのセッションは次回のリフレッシュ（1 時間以内）で終了しますが、これらのトークンは終了しません。プロバイダーに本人について問い合わせるのは、リフレッシュだけだからです。[SCIM](#deprovisioning-with-scim) を設定している場合は、プロバイダーが次回のプロビジョニング実行時に Loom へ通知し（Okta ではユーザーの無効化時、Entra ではそのサイクル内）、Loom はそのユーザーと本人が作成したすべてのトークンを失効させます。SCIM がない場合は、退職時にそのユーザーを失効させてください。本人が作成したすべてのトークンも同時に終了します。`loom revoke-token --subject <their subject>` を実行するか、どこからでも [`POST /v1/admin/revoke_subject`](#deprovisioning-without-scim) を呼び出します。
- サインイン、デバイスの承認と拒否、MCP の同意、JIT アカウント、セッションの終了はすべて、監査ログに `auth.*` の行として書き込まれます。
  `auth.sso_signin`、`auth.signin_denied`、`auth.device_approved`、
  `auth.device_denied`、`auth.connect_approved`、`auth.connect_denied`、
  `auth.jit_provisioned`、`auth.sso_linked`、`auth.sso_unlinked`、`auth.sso_link_declined`、`auth.password_set`、`auth.agent_claimed`、`auth.machine_created`、`auth.machine_token`、`auth.machine_disabled`、`auth.agent_provisioned`、`auth.platform_admin_minted`、
  `auth.session_revoked`、`auth.scim_deactivated`、`auth.scim_reactivated`、
  `auth.scim_deleted`、`auth.scim_collateral`。

<a id="deprovisioning-with-scim"></a>

## SCIM によるデプロビジョニング

アイデンティティプロバイダーは、SCIM 2.0（RFC 7643/7644）を使って、アプリに無効化を通知します。Loom はこの通知を受け付けます。プロバイダーが通知を送ると、その人物のセッションと、その人物が作成したトークンは、リクエストを受けた Loom プロセスが直ちに拒否します。同じレプリカか別のレプリカかを問わず、他のすべてのプロセスも、次回の失効情報の更新（`LOOM_JWT_REVOCATION_CACHE_TTL_SECONDS`、デフォルトは 30 秒）で拒否するようになります。その間に新しいトークンを発行するプロセスはありません。すべての発行処理が ClickHouse から失効情報を読み取るためです。長いランダムなトークンを設定して再起動します。

```bash
LOOM_SCIM_TOKEN=$(openssl rand -hex 32)
```

空（デフォルト）の場合、SCIM は無効になり、そのルートもマウントされません。トークンが 32 文字未満の場合、または SCIM が設定されているのにサインインが SSO（`LOOM_OAUTH_LOGIN_PROVIDER=oidc`）でない場合や認証がオフの場合、Loom は起動を拒否します。この場合、無効化しても誰も拒否されないためです。`loom doctor` でも同じ内容が表示されます。このトークンは `/scim/v2` が受け付ける唯一の認証情報です。クライアントシークレットと一緒に保管してください。

プロバイダーを拒否しないままローテーションするには、両方のトークンをカンマ区切りで列挙してレプリカをロールします。次にプロバイダーに新しいトークンを設定し、その後で古いトークンを削除して再度ロールします。

```bash
LOOM_SCIM_TOKEN="$OLD_TOKEN,$(openssl rand -hex 32)"
```

Loom は SCIM ユーザーをメールアドレスで識別します。リクエストの `emails` エントリのうちアドレスを持つものから、primary とマークされたもの、なければ最初の work のもの、それもなければ最初のものを使います。アドレスがない場合は `userName` を使います（`userName` がそのアドレスと異なる状態でユーザーを作成または名前変更すると、Loom は警告をログに記録します）。このアドレスは、プロバイダーが ID トークンの `email` クレームに入れるものと一致している必要があります。サインイン時に渡されるのがそのクレームだからです。

Okta では、[Okta のセットアップ](#okta-setup)で作成したアプリ統合で次の手順を行います。

1. **General → App Settings → Edit** で **Provisioning** を **SCIM** に設定し、保存します。
2. **Provisioning → Integration → Edit:**
   - **SCIM connector base URL:** `<public Loom URL>/scim/v2`
   - **Unique identifier field for users:** `userName`
   - **Supported provisioning actions:** Push New Users と Push Profile Updates
   - **Authentication Mode:** HTTP Header。`LOOM_SCIM_TOKEN` の値をベアラートークンとして設定します。

   **Test Connector Configuration** を実行してから保存します。

3. **Provisioning → To App → Edit:** **Create Users**、**Update User Attributes**、**Deactivate Users** を有効にして保存します。Loom が保持する属性は `userName`（名前変更は保持されます）と `emails` リストだけで、キーとなるメールアドレスは変更できません。
   更新を有効にしている場合、メールアドレスを変更すると Okta ではタスクの失敗として表示されます（Entra も同じ拒否をログに記録します）。その場合は[人物のメールアドレスの変更](#changing-a-persons-email)に従ってください。更新を無効にしている場合、Okta はメールアドレスが変更されたことを通知しません。その人物が次にサインインすると新しいアドレスで新しいアカウントが作られ、古いアドレスに対する後の無効化はそのアカウントに及びません。
4. **General → Sign On** で **Application username format** を **Email** に設定します。Loom は人物をメールアドレスで識別します。

すでに割り当て済みの人物は、次に割り当てまたは更新したとき、あるいは **Assignments → Provision User** からプッシュされます。他のプロバイダー（OneLogin など）も、同じベース URL とベアラートークンを使用します。

Okta は、無効化（Okta で人物を無効にした場合、またはアプリの割り当てを解除した場合）を、`PATCH` または `PUT` による `active: false` として送信し、`DELETE` は送信しません。

**Microsoft Entra ID** では、サインインに使うエンタープライズアプリケーションで次の手順を行います。

1. **Provisioning → Get started** で **Provisioning Mode** を **Automatic** に設定します。
2. **Admin Credentials:** **Tenant URL** に `<public Loom URL>/scim/v2` を、**Secret Token** に `LOOM_SCIM_TOKEN` の値を設定します。**Test Connection** を実行してから保存します。
3. **Mappings:** ユーザーマッピングはそのままにします。Entra は `userPrincipalName` を `userName` に、`mail` を `emails[type eq "work"].value` にマッピングし、ID トークンの `email` クレームは `mail` なので、Loom は `mail` からメールアドレスを取得します。`mail` を持たないユーザーについては、UPN ではなく ID トークンが持つアドレスから `mail` をマッピングしてください。UPN は別のアドレスである場合があります。`userName`（デフォルト）でのマッチングも、`emails[type eq "work"].value` でのマッチングも使用できます。**Provision Microsoft Entra ID Groups** は **No** に設定します。Loom はグループを保持せず、作成を拒否するため、Entra では毎サイクル失敗として数えられます。
4. **Settings → Scope:** **Sync only assigned users and groups** を選択し、**Start provisioning** を実行します。

Entra は、ユーザーが無効化、ソフトデリート、または割り当て解除されたときに `active: false` を送信し、`DELETE` はハードデリート時（ソフトデリートの 30 日後）にのみ送信します。プロビジョニングは約 40 分のサイクルで行われるため、無効化は次のサイクルで Loom に届きます。ユーザーの **Provision on demand** を使うと直ちに送信されます。

各リクエストに対する Loom の動作は次のとおりです。

- **ユーザーの作成**ではメールアドレスを記録するだけで、アカウントは作りません。アカウントは、その人物の最初の SSO サインイン時に作成されるか（JIT）、SCIM がない場合と同様に既存のアカウントに到達します。同じメールアドレス、または別のユーザーがすでに持つ `userName` での 2 回目の作成には 409 を返します。
- **更新**（`PUT`、または `active`、`userName`、`emails` の `PATCH`）では、新しい `userName` が保持されます（別のユーザーがすでに持つ場合は 409）。送信された `emails` リストも保持されます。`PATCH` は操作をそのリストに順に適用し、結果のリストが上記の規則で別のメールアドレスをキーにする場合、そのリクエストは拒否されます（400 `mutability`）。その人物が別のアカウントにサインインすることになり、古いメールアドレスに対する後の無効化がそのアカウントに及ばないためです。どのエントリも選択しないフィルター経由の `add` または `replace` はエントリを追加します。Entra の書き込みがそれを前提としているためです。それ以外のアドレスは追加、変更、削除できます（[人物のメールアドレスの変更](#changing-a-persons-email)を参照）。`active: false` も設定している拒否されたリクエストは、それでも無効化します。プロバイダーは退職者の変更をまとめて送信し、400 を再試行しないためです。本文に別のユーザーの `id` を指定した `PUT` は、何かを適用する前に拒否されます。
- **無効化**（`PATCH` または `PUT` による `active: false`、または `DELETE`）では、そのメールアドレスでの SSO サインインが到達しうるすべてのサブジェクト（そのアドレスを名前に持つ各 SSO アカウントと、それにリンクされた各パスワードアカウント。組織は問わない）を即座に失効させます。対象は、すべてのセッションと、その人物が作成したすべてのサービスアカウントおよび MCP トークンです。それらのトークンは、Tokens リストで `scim` により失効したものとして表示され、名前は再び使用できるようになります。再有効化しても元には戻りません。そのようなトークンが制限付き名前空間で自分の名義で持っていた権限付与は、名前空間の権限付与リストに残りますが、何にも到達しません。リストを整理するには、そこで失効させてください。無効化が続いている間は、そのメールアドレスでの SSO サインインは、まだどのアカウントにも到達しない場合でも拒否されます（「this account is deactivated」）。アカウント、その権限付与、データは残ります。これは消去ではありません。その人物が登録したボットと CI トラスト（`loom bot`）は組織のものであり、動作し続けます。停止したい場合は `loom bot disable` で無効にしてください。メールアドレスを名前に持つがそのアドレスにリンクされたことがない（SSO サインインで採用、リンク、証明されていない）パスワードアカウントには、SSO サインインは到達しないため、そのまま残ります。`loom revoke-token --subject` で失効させるか、退職処理の前に採用してください（[アカウント](#accounts)）。同様に、オペレーターがメールアドレス自体をサブジェクトとして発行したトークン（`loom mint-token --subject <email>`）が、サブジェクトがハンドルである採用済みアカウントにある場合は、`loom revoke-token --subject <email>` でそのメールアドレスを失効させます。サブジェクトは名前であり、組織のものではありません。メールアドレスがそのサブジェクトに到達しない組織で、同じ名前がアカウントを所有している、または権限付与を持っている場合（別の人物の `alice` など）でも、そのサブジェクトは失効され、Loom は警告をログに記録して、それらの組織を示す `auth.scim_collateral` を監査に記録します。`loom revoke-token --list`（`scim→<it>`）で確認し、他の人物のものであれば `loom revoke-token --subject <it> --issued-before <now> --scim` で返却します。新しいトークンは使用でき、無効化前のトークンは失効したままです（Loom は、それより前の `--issued-before` を拒否します）。プロバイダーが無効化を繰り返しても、ユーザーを削除しても、返却した状態は保たれますが、その人物が再有効化された後に再び無効化されると、再び即座に失効されます。その場合は、もう一度返却してください。
- **再有効化**（`active: true`）では、その人物は再びサインインできます。以前のトークンは失効したままで、新しいものを作成します。別の無効化済みまたは削除済みユーザーのメールアドレスがまだ到達するサブジェクト（2 つのアドレスが 1 つのアカウントに到達する場合）は失効したままで、Loom は残した各サブジェクトについて警告をログに記録します。どのアドレスも到達しなくなると（最後のユーザーが再有効化されるか、オペレーターが `loom sso link` でアカウントを別のアドレスに移した場合）、そのアドレスが到達する有効なユーザーに対する次の `PUT` または `PATCH` で、そのサブジェクトは解放されます。Okta は、**Update User Attributes** が有効な場合にのみプロフィール変更時にこれを送信し、Entra はマッピングされた属性が変更されたときに送信します。それ以外の場合、または直ちに行いたい場合は、オペレーターとして `loom revoke-token --subject <it> --issued-before <now> --scim` で返却します。再有効化の応答は約 6 秒後（無効化の直後に行った場合は最大 11 秒後）で、すべてのレプリカのクロックがカットオフを過ぎた後に返ります。そのため、その後のサインインでは有効なトークンが得られます（待機中のサインインではカットオフ前のトークンになり、すでに失効しています）。その間に送られた再試行は、残りの時間を待ちます。同じレプリカか別のレプリカかを問わず、他のプロセスは、次回の失効情報の更新まで新しいセッションを拒否し、その後に受け入れます。
- **削除**は無効化を行い、以降そのユーザーには 404 を返します（`auth.scim_deleted` が監査に記録されます）。プロバイダーが再びそのユーザーを作成すると、再有効化され、同じ待機の後に応答します。その作成の再試行は、残りの時間を待ってから 409 を返します。

SCIM は、失効情報をオペレーターのものとは別に保持します。無効化で失効される各サブジェクトには、`loom revoke-token --subject` が書き込むものとは別に、専用の SCIM 失効が作られ、どちらかが失効を示している間、そのサブジェクトは失効しています。SCIM はオペレーターの失効を変更せず、オペレーターの失効も SCIM の失効を変更しません。その人物が無効化されている間に、期限付きの `--expires-at` や `--issued-before` による解除を行っても、その人物は入れません。また、再有効化は SCIM の失効だけを解除するため、オペレーターが失効させたサブジェクトは失効したままです。サブジェクトの SCIM 失効を変更できるのは `--scim` だけです。

Loom は、各 SCIM ユーザーの行を `loom.scim_users` に保持します（userName、メールアドレス、プロバイダーが送信した `emails` リスト、失効させたサブジェクト、有効かどうか）。保持期間はデプロイメントが存続する間で、削除済みユーザーも含みます。この行が、無効化された人物の再入場を防ぎます。`DELETE` は `emails` リストを消去しますが、メールアドレスは残ります。リクエストは冪等なので、プロバイダーの再試行は安全で、並行して実行されます。待機が生じるのは、共有アカウントに到達する人物のリクエスト同士だけです（処理中のものには 503 を返し、プロバイダーが再試行します）。対応するフィルターは `userName eq "<userName>"` と、メールアドレスに対する `emails[type eq "work"].value eq "<email>"`（または `emails.value eq`）です。後者は、そのアドレスを持つ `emails` エントリがある（最初のものについては `work` エントリ）すべてのユーザーに、大文字小文字を区別せずに一致し、そのアドレスをキーとするユーザーだけには限りません。`GET /Users`、`GET /Users/{id}`、`GET /ServiceProviderConfig` は RFC 7644 のとおりに応答し、`GET /Groups` は空のリストを返します。

SCIM を無効にする（`LOOM_SCIM_TOKEN` を空にする）と `/scim/v2` がマウント解除されるため、誰の無効化も再有効化も行われなくなり、全員がそのままの状態に置かれます。無効化されたメールアドレスでの SSO サインインは引き続き拒否され、無効化された人物のサブジェクトは、新しいトークンを含めて、オペレーターが `loom revoke-token --subject <it> --issued-before <now> --scim` で個別に解除するまで失効したままです。これで可能になるのはそのサブジェクトの新しいトークンの使用（古いトークンは失効したまま）であり、サインインではありません。SCIM を無効にした後で、無効化された人物が再びサインインできるようにするには、`LOOM_SCIM_TOKEN` を再設定し、プロバイダーから、または手動で、その人物に `active: true` を送信します。Loom を使い続けるべき人物は、先にプロバイダーで再有効化してください。

<a id="changing-a-persons-email"></a>

### 人物のメールアドレスの変更

Loom は SCIM ユーザーをアドレスで識別し、その変更を拒否する（400）ため、新しいアドレスは新しい SCIM ユーザーとして届く必要があります。それまでは、新しいアドレスでのサインインは、どの SCIM ユーザーにも到達しないアカウントを作り、古いアドレスの無効化はそれに及びません。その人物が新しいアドレスでサインインする前に、次の手順で変更してください。

1. プロバイダーでその人物をアプリから削除します。これにより古いアドレスが無効化され、そのアドレスが到達するアカウントが失効します。
2. Entra では、古い SCIM ユーザーも削除します。Entra は `userName`（UPN）でユーザーを照合し、メールアドレスの変更では UPN は変わらないため、再割り当てしても古いユーザーが見つかり、新しいアドレスが Loom に拒否される変更として送信されます。その id は `GET /scim/v2/Users?filter=userName eq "<upn>"` で調べ、`DELETE /scim/v2/Users/<id>` で削除します。どちらも SCIM トークンを使います。Okta は `userName` でユーザーを検索し、Okta ではそれがメールアドレスなので、新しいユーザーを自動的に作成します。
3. その人物を再度割り当てます。プロバイダーが新しいアドレスの SCIM ユーザーを作成します。

古いアカウントについては次のとおりです。

- パスワードアカウント：`loom sso link --email <new> --org <org> --namespace <ns> --apply` で新しいアドレスに向けます。古いアドレスはそのアカウントに到達しなくなり、新しいユーザーに対する次の `PUT` または `PATCH` で解放されます（直ちに返却するには `loom revoke-token --subject <it> --issued-before <now> --scim` を使います）。
- SSO サインインで作られたアカウント：移動するコマンドはなく、その人物が新しいアドレスで最初にサインインすると新しいアカウントが作られます。古いアカウントの名前空間への権限を付与してください。古いアカウントとそのデータは失効した状態で残ります。

<a id="deprovisioning-without-scim"></a>

## SCIM を使わないデプロビジョニング

人が退職するタイミングを把握しているシステム（たとえば、その人のサインインも発行しているコントロールプレーン）は、代わりに管理 API でその人を失効させます。プラットフォーム管理者は次のように送信します。

```bash
loom call /v1/admin/revoke_subject --data \
  '{"org":"acme","subject":"lee@acme.io","reason":"left","issued_before":"2026-01-31T12:00:00Z"}'
```

Loom は、そのサブジェクトと、組織のディレクトリが対応付けているすべての表記を失効させます。メールアドレスが検証済みかどうかは問いません（グラントは検証済みのペアのみを対象に許可されます）。メールアドレスは、それを名指しする各アカウントのログインハンドルに対応し（SSO アカウントのサブジェクトはその名前空間、`u-…` です）、ハンドルはそのメールアドレスに対応します。それぞれについて、サブジェクトがそれであるすべてのトークン、それが作成したトークンやそのトークンから派生したすべてのトークン、そのサインインセッションのすべてのリフレッシュが、リクエストを受け付けたプロセスでは即座に拒否され、他のすべてのプロセスでは次回の失効情報の更新時に拒否されます。すべてのトークン発行は ClickHouse から失効情報を読み取るため、そのサブジェクトに対するサインイン、デバイス承認、MCP 接続でもトークンは発行されません。失効させたサービスアカウントと MCP トークンは、Tokens 一覧に `admin:<you>` による失効として表示され、SCIM による無効化の場合と同様に、その名前は再び使えるようになります。アカウント、そのグラント、データは残ります。これは消去ではありません。

`issued_before`（オフセット付きの RFC 3339 形式）を指定すると、失効の対象がその時刻より前に発行されたものに限定されます。この限定は恒久的です。プラットフォームがデプロビジョニングを行う場合は現在時刻を送信します。そうすれば、その人が後で再招待されたときに、次回のサインイン、新しいデバイス承認、新しい MCP 接続が機能します。Loom はその時刻を次の秒に切り上げ、さらにレプリカ間の時計のずれとして許容する 5 s を加えます。これにより、どのレプリカでもそれより前に発行されたものは残りません。その後のわずかな秒数の間に発行されたトークンも拒否されます。サーバーの時計より先の時刻は現在として扱われるため、呼び出し側の時計が進んでいても、この先のサインインまで拒否されるカットオフが設定されることはありません。`issued_before` を指定しない場合、失効は無条件になります。`loom revoke-token --subject` が書き込むものと同じで、サブジェクトのすべてのトークンが、発行が前でも後でも恒久的に拒否されます。これは永久的な締め出し向けの形式です。リクエストが、サブジェクトがすでに持つ失効を弱めることはありません。カットオフはサブジェクト自身の失効の横に（オペレーターのカットオフとして、下の一覧では `kind: cutoff`）記録され、後ろにしか動きません。そのため、無条件の失効はそのまま有効であり、期限付きの失効（`loom revoke-token --expires-at`）は期限が切れるまで有効で、その後はカットオフが効き続けます。無条件のリクエストは、すでに無条件で恒久的な失効をそのままにします。

```json
{
  "subjects": ["lee@acme.io", "u-lee-1a2b3c4d"],
  "org": "acme",
  "revoked_at": "2026-01-31T12:00:00",
  "reason": "left",
  "issued_before": "2026-01-31T12:00:06Z",
  "outright": [],
  "sessions": 2,
  "tokens": 3
}
```

応答の `issued_before` は、無条件で失効していないサブジェクトに現在有効なカットオフです。サブジェクトごとに異なる場合は最も早いものになります。リクエストが求めたカットオフか、以前のリクエストが設定したより後のカットオフです。無条件のリクエストの場合と、すべてのサブジェクトが無条件で失効している場合は `null` になります。`outright` は、現在無条件で拒否されているサブジェクトを示します。無条件のリクエストの後はそのすべてで、カットオフの後は、無条件の失効（自身のもの、期限付きかどうかを問わず、または SCIM のもの）がなお有効なサブジェクトです。`sessions` は、失効によって終了するそれらのサブジェクトのサインインセッション（それぞれカットオフより前にリフレッシュされたもの）の数、`tokens` は、それらが直接、またはそのトークンを通じて作成し、失効によって終了するトークンの数です。サブジェクトは名前であり組織のものではないため、失効はすべての組織で有効です。`org` は、表記の取得元となるディレクトリと、各 `token.revoked` 行が記録される監査ログを指定します。エンドユーザーのサブジェクト `<org>/user:<id>` は、自身の組織を指定する必要があります。ディレクトリを読み取れない場合は、何も失効されず、リクエストは失敗します。繰り返しのリクエストは同じ応答を返し、それ以上は何も書き込みません。そのため、呼び出し側は 200 が返るまで再試行します。失効が書き込まれた後の失敗（トークンへのマークが完了しなかった場合）は、再試行で完了します。

`GET /v1/admin/revocations?subject=<subject>` は、サブジェクトの失効を一覧表示します。サブジェクト自身のもの、オペレーターのカットオフ、SCIM のものが対象です（`kind`）。`subject` を指定しない場合は、`loom revoke-token --list` と同様に、期限切れでないすべての失効を新しい順に一覧表示します。`since`（RFC 3339）を指定すると、それ以降に書き込まれたものだけが残り、`limit`（1 から 10000、デフォルトは 1000）で応答の件数を制限します。Python SDK では `agent.deployment.routes.revocations(params={"subject": ...})` としてこれらを渡します。無条件で失効した人を再び受け入れるには、失効を削除するのではなく範囲を狭めます。`loom revoke-token --subject <it> --issued-before <now>` を使うと、その時点以降に作成されたトークンは機能し、それ以前のものはすべて無効のままになります。

<a id="behind-a-proxy"></a>

## プロキシの背後で運用する場合

15 分あたりのサインイン回数の上限（誤ったデバイスコード 10 回、新規のデバイスサインイン 30 回、ID プロバイダーのサインイン開始 300 回、失敗したコールバック 30 回）は、クライアントアドレスごとに数えられ、IPv6 の /64 は 1 つとして扱われます。`LOOM_TRUSTED_PROXIES` にプロキシのアドレスを設定すると、すべてのユーザーに対してプロキシのアドレスが使われるのではなく、ユーザー自身のアドレスが使われます。

Loom が発行者（issuer）自身のホストで ID プロバイダーに到達できない場合（たとえば、公開名がブラウザーからしか到達できないアドレスに解決される場合）は、`LOOM_OIDC_BACKCHANNEL_BASE_URL` に、プロバイダーへ到達できるアドレスを設定します。例として `http://idp.example:8080` のように、スキーム、ホスト、省略可能なポートだけを指定し、それ以外は含めません。すると、Loom が発行者のホストに対して行う呼び出しは、パスをそのままにして、`Host` ヘッダーに発行者のホストを入れた状態で、このアドレスに送られます。対象は、ディスカバリードキュメント（`<base>/<issuer path>/.well-known/openid-configuration`）、トークンエンドポイントと失効エンドポイント、および ID トークンの検証に使う鍵です。ブラウザーは引き続き発行者の `authorization_endpoint` へ移動します。ドキュメントが別のホストのエンドポイントを指定している場合は、そのまま呼び出されます。bot trust の鍵は、常にそれが指定する https アドレスから取得されます。また、ドキュメントとすべての ID トークンは、発行者として引き続き `LOOM_OIDC_ISSUER` を示している必要があります。これらの呼び出しはいずれもリダイレクトに従いません。プレーンな `http` のベースを使うと、クライアントシークレットが暗号化されずに送信されます。信頼できるネットワークでのみ使用してください。

<a id="clickhouse-keeper"></a>

## ClickHouse Keeper について

サインインでは、コード、デバイスグラント、および各セッションの現在のリフレッシュトークンを ClickHouse Keeper に保持し、compare-and-set でのみ変更します。これにより、それぞれが正確に 1 回だけ消費されます。Loom には Keeper が必須であり、Keeper がない場合は起動を拒否します。`/v1/health` が `oauth_signin_state_full` を報告した場合、Keeper テーブルがキー数の上限に達しています（デバイスサインインの大量発生が原因です）。キーが期限切れになるまで、新しいサインインには 503 を返します。そのため、プロキシでネットワーク単位にサインイン用ルートへレート制限をかけてください。

<a id="upgrading-to-this-build"></a>

## このビルドへのアップグレード

このビルドより前に確立された MCP 接続は、もう一度サインインが必要です。これらのリフレッシュトークンには終了させるセッションがなかったため、ローテーションされません。以前のビルドがまだ稼働している間（ローリングアップグレードやロールバックの場合）、そのビルドはセッションもオペレーターのカットオフも認識しません。セッションが終了したアクセストークンは、その 1 時間のあいだ以前のビルドで引き続き使えます。ボットの無効化や adopt で無効になったトークンも同様です。アカウントを adopt する前、またはログアウトやボットの無効化に頼る前に、ロールアウトを完了してください。以前のビルドは SCIM を提供せず、無効化も SCIM による失効も読み取りません。SCIM で無効化された人は、以前のビルドでは引き続きサインインでき、そのトークンも引き続き使えます。`LOOM_SCIM_TOKEN` は、すべてのレプリカがこのビルドで動作してから設定してください。また、無効化された人がいる間は、このビルドより前にロールバックしないでください。以前のビルドではそれらの人がサインインできてしまいます。ロールバックの前に、該当する各人を ID プロバイダーでブロックし（一時停止するか、アプリケーションから削除します）、各人が到達できる subject を `loom revoke-token --subject` で失効させてください。どのアカウントにも到達しない無効化済みメールアドレスには、失効させる subject がありません。そのアドレスを以前のビルドから締め出せるのは、プロバイダー側のブロックだけです。

別のトークンによって作られたトークンは、無効化によってその人のトークン名が解放されるときに、上位にある subject をたどって見つけられます。このビルドは各トークンにそれらを記録し、新しいトークンが名前を再利用する前に、子トークンへ引き継ぎます。このビルドより前に作られたトークンは、その上位にある名前がこのビルドより前に再利用されていた場合、チェーンの先頭にいる人を失います（その後に再利用された名前が引き継ぐのは、残っていた分だけです）。そのトークンは引き続き拒否されます（失効は委任チェーンを通じて及びます）が、有効なものとして一覧に残り、名前も保持したままです。上位の subject がすべてトークンで、そのどれも有効ではなく、したがって人にたどり着かないトークンを、次のクエリで一覧表示します。

```sql
SELECT org, name, sa_subject, created_by FROM loom.service_accounts FINAL
WHERE revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now())
  AND arrayAll(s -> match(s, '^sa:[^:]+$'), arrayConcat([created_by], lineage))
  AND (org, name) NOT IN (
    SELECT org, name FROM loom.service_accounts FINAL
    ARRAY JOIN arrayConcat([created_by], lineage) AS above
    WHERE above IN (
      SELECT sa_subject FROM loom.service_accounts FINAL
      WHERE revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now())))
```

ここでは、マシントラストのエージェント（`sa:<trust>:<agent>`）は人として数えられます。`loom mint-token --subject sa:…` で発行した subject から作られたトークンは、実行のたびに一覧に表示されますが、これらには該当しません。そのまま残してください。このビルドより前に、すでに失効されたトークンによって作られたトークンも一覧に現れます。それはすでに無効であり、失効させると名前が解放されます。一覧に出たそれ以外のトークンは、それぞれの名前空間のいずれかの管理者として、`/v1/me/service_accounts.revoke` とその `name` で失効させてください（作成者は人ではなくトークンなので、誰の自分用の一覧にも載りません。名前空間管理者の Tokens 一覧には、最新の 200 件の中に表示されます）。その後、もう一度クエリを実行してください。失効させたトークンの下にあるトークンは、その上位が失効された時点で一覧に現れます。一覧に残るのが、自分で発行した subject から作られたトークンだけになったら終了です。以前のビルドがまだ稼働している間は、そのビルドが一覧表示、失効、または名前の再利用を行うトークンには、系統が記録されません。

手順が両方のビルドにまたがるブラウザーのサインイン（コードの交換や、ID プロバイダーのコールバック）は失敗し、やり直しになります。SDK と `loom login` はこれを吸収します。このビルドは、トークンとデバイスのサインインの応答に `Loom-Sessions` ヘッダーを付けます。そのため、サーバーが一度これを送った後は、ヘッダーのない拒否は以前のビルドによるものと判断され、セッションを維持するか（リフレッシュは再試行を指示します）、ポーリングを続けます（デバイスのサインイン）。ヘッダーを削除するプロキシがある場合に失われるのは、この動作だけです。サインインがアップグレードをまたぐ数を減らすため、ロールアウトは素早く行ってください。Helm チャートでは、レプリカ数の全体を一度にサージさせます。

<a id="turning-sso-off"></a>

## SSO をオフにする

`LOOM_OAUTH_LOGIN_PROVIDER=password` を設定する（または削除する）と、再起動後にオフになります。パスワードアカウントは、引き継いだものやリンクしたものも含め、再びパスワードでサインインします。リンクによってパスワードが削除されることはありません。SSO でサインインしたセッションは次回の更新時に終了し、その所有者は再度サインインします。JIT で作成されたアカウントにはパスワードがありません。所有者にパスワードを設定させるには、次のコマンドを実行します。

```bash
loom sso password-link --email lee@example.com
```

このコマンドは、パスワードを一度だけ設定できるリンクを出力します。リンクは `LOOM_PASSWORD_LINK_TTL_SECONDS` の間（デフォルトでは 1 日）有効で、SSO がオフの間のみ使えます。アカウントはリンクされたままなので、SSO を再びオンにすればそのアカウントに到達できます。SSO のオン／オフを切り替えても、ボット（`loom bot`）とオペレーターが発行したトークンには影響しません。

<a id="break-glass"></a>

## 緊急時のアクセス

SSO が有効な場合、運用担当者を含め、誰もパスワードでサインインできません。プロバイダーがダウンしているときは、サーバーホスト上で `docker exec loom-server loom mint-token --subject <you> --org <org> --namespaces <ns>` を実行してトークンを発行し、`/me#token=<token>` を開いてください。これはサインイン用のランディングページで、リダイレクトは行いません（`/` は `LOOM_DASHBOARD_REDIRECT_URL` に従うため、ブラウザーがトークンを持ったまま遷移してしまいます）。

<a id="other-providers"></a>

## その他のプロバイダー

`<issuer>/.well-known/openid-configuration` でディスカバリを提供している OIDC プロバイダーであれば、同じ設定で動作します。

- **Microsoft Entra ID：** `LOOM_OIDC_ISSUER=https://login.microsoftonline.com/<tenant>/v2.0`。ID トークンに `email_verified` が含まれないことが多く、Loom はそのようなトークンを拒否します。これを明示するプロバイダー設定を使用してください。
- **Google：** `LOOM_OIDC_ISSUER=https://accounts.google.com`。Google は Loom にリフレッシュトークンを発行しないため、セッションは 1 時間で終了します。
- **Keycloak：** `LOOM_OIDC_ISSUER=https://<host>/realms/<realm>`。
