自社IdPによるエアギャップ化されたDevinのSSO

このドキュメントはDevinの連邦政府向け導入環境を対象としています。Devinドキュメントに戻る

デフォルトでは、エアギャップ化されたbuildへのアクセスはライセンスファイルのみによって制御されます。これに加えて、各ユーザーに自社のOIDCアイデンティティプロバイダーへのサインインを必須にすることもできます。SSO (シングルサインオン) はライセンスに上乗せする形で適用されます。ライセンスは引き続き必須であり、ログインフローは設定した発行者に対して実行されます。

認証ファイルを作成する


デフォルトのパス	`/etc/devin/auth.json`
デフォルトのパス (Windows)	`C:\ProgramData\Devin\auth.json`
上書き設定	`DEVIN_AUTH_FILE=<path>`

このファイルでは、モードを 1 つだけ指定します。ファイルが存在しない場合、製品は "mode": "license" が指定されているものとして動作します。

/etc/devin/auth.json

{
  "schema_version": 0,
  "mode": "sso",
  "issuer": "https://sso.example.com",
  "client_id": "devin-cli",
  "scopes": ["openid", "profile", "email"],
  "groups_claim": "groups",
  "required_group": "devin-users",
  "additional_endpoint_hosts": []
}

フィールド	必須	説明
`schema_version`	はい	`0` を指定する必要があります。
`mode`	はい	ログインを必須にする場合は `"sso"`、ライセンスのみでアクセスする場合は `"license"` (ファイルが存在しない場合のデフォルト) を指定します。
`issuer`	はい (sso)	OIDC 発行者の URL。`https://` で始まる必要があり (プレーンな `http://` はループバックホストの場合のみ許可されます) 、クエリ文字列、フラグメント、埋め込みの認証情報を含めることはできません。検出は `<issuer>/.well-known/openid-configuration` に対して行われます。
`client_id`	はい (sso)	IdP に登録したクライアント。
`scopes`	いいえ	デフォルトは `openid profile email` です。指定する場合は `openid` を含める必要があります。IdP が `offline_access` をアドバタイズしている場合は、リフレッシュトークンが付与されるよう自動的にリクエストされます。
`groups_claim`	いいえ	グループメンバーシップを格納する ID トークンのクレーム。デフォルトは `groups` です。
`required_group`	いいえ	設定した場合、この値がグループクレームに含まれていなければログインは拒否されます。
`additional_endpoint_hosts`	いいえ	IdP の検出ドキュメントでエンドポイントのアドバタイズを許可する追加のホスト。必要な場合以外は空のままにしてください。詳しくは検出されたエンドポイントは発行者上にある必要がありますを参照してください。

不明なフィールドはエラーになります。license モードで指定できるのは schema_version と mode のみです。

IdP がプライベート CA によって発行された証明書を使用している場合は、CLI がその証明書を信頼するよう、DEVIN_CA_BUNDLE に PEM バンドルを指定してください。詳しくはネットワークと証明書を参照してください。

IdP にクライアントを登録する

CLI は OIDC の PKCE (S256) を用いた認可コードフローを公開クライアントとして実行するため、クライアントシークレットは使用しません。登録するクライアントは、次の要件を満たす必要があります。

client_id に指定した ID(例: devin-cli)を持つ公開クライアント(クライアントシークレットなし)であり、認可コードグラントが有効化され、PKCE メソッドが S256 に設定されていること。
http://127.0.0.1/callback が有効なリダイレクト URI として登録されていること。CLI は、ブラウザフローではランダムなループバックポート(http://127.0.0.1:<port>/callback)で待ち受け、手動フローでは固定の http://127.0.0.1/callback を利用します。RFC 8252 では IdP はループバックポートを無視すべきとされていますが、お使いの IdP が無視しない場合は、これにマッチするワイルドカードを登録してください。
required_group を利用する場合は、groups_claim で指定したグループメンバーシップのクレーム(デフォルトは groups)が ID トークンに含まれていること。
IdP がリフレッシュ時に ID トークンを返し(openid スコープが付与されていれば、ほとんどの IdP が返します)、かつこのクライアントの ID トークンの有効期間が短く設定されていること。その理由については、失効の伝播の仕組みを参照してください。

ワークステーションのターミナルからログインします：

devin auth login

Opening your browser to sign in with your identity provider...
If the browser does not open, visit:

  https://sso.example.com/authorize?client_id=devin-cli&...

(Use `devin auth login --force-manual-token-flow` on headless machines.)
Logged in as jsmith via https://sso.example.com.
Token expires at 2026-03-02 15:04:05 UTC.

ヘッドレスホスト上や SSH 経由で作業している場合は、手動フローを利用してください。CLI に URL が表示されるので、任意のマシンのブラウザでその URL を開きます。サインインすると、ブラウザは 127.0.0.1 の URL にリダイレクトされますが、このページは読み込まれません。その URL 全体 (クエリパラメーターを含む) をコピーし、ターミナルに貼り付けてください。

devin auth login --force-manual-token-flow

Open this URL in a browser (on any machine) and sign in:

  https://sso.example.com/authorize?client_id=devin-cli&...

After signing in, the browser is redirected to a 127.0.0.1 URL that will not load — copy that full URL (including its query parameters) and paste it here.
Paste the full redirect URL:

Devin Desktop は、同梱のエージェントを通じて同じログイン情報を利用します。サインインしていないユーザーには、作業を開始する前に Devin の設定でサインインするよう求めるメッセージが表示されます。

ステータスの確認とサインアウト

devin auth status

Auth mode: SSO (issuer: https://sso.example.com)
Status: logged in
User: jsmith
Subject: 6f1c2a0e-...
Groups: devin-users
Token expires at 2026-03-02 15:04:05 UTC.

キャッシュされたログイン情報が存在しない場合や更新できなくなった場合は、Status: not logged in (<reason>) と出力され、続けて Run \devin auth login` to sign in.` と表示されます。

devin auth logout

Logged out: local SSO tokens deleted.

ログアウトはローカルでのみ処理されます。トークンキャッシュを削除するだけで、IdP への通信は発生しません。

CLI が検証する内容

ID トークンはローカルで検証されます。検証対象は、IdP の JWKS による署名、iss、aud、有効期限 (120 秒までのクロックスキューを許容) 、ログイン時の nonce、およびグループによるアクセス制限です。ID トークンとリフレッシュトークンは、所有者のみがアクセスできる権限 (0600) でローカルの認証情報ストアにキャッシュされ、IdP を通じてバックグラウンドで自動的に更新されます。 SSO (シングルサインオン) が設定済みで、有効なログインが存在しない場合 (かつバックグラウンドでの更新にも失敗した場合) 、CLI は起動時にエラーを表示して終了し、devin auth login を実行するようユーザーに促します。 CLI は IdP からの HTTP リダイレクトには従いません。検出、JWKS、トークンのいずれかのエンドポイントから 3xx が返された場合、ログインは失敗し、該当するエンドポイント名を含むエラーが表示されます。そのため、issuer には IdP が実際に応答する URL を指定する必要があります。

検出されたエンドポイントは発行者と同じオリジンである必要がある

検出によって取得した authorization_endpoint、token_endpoint、jwks_uri は、issuer とスキーム、ホスト、ポートが同じである必要があります (デフォルトポートは同一とみなされます) 。それ以外のホスト上のエンドポイントは拒否され、ログインは次のようなエラーで失敗します:

IdP discovery document advertises jwks_uri 'https://keycloak.corp.internal:8443/realms/devin/protocol/openid-connect/certs'
on host 'keycloak.corp.internal:8443', which is not the configured issuer's host 'sso.corp.example:443';
refusing to trust it. If this IdP really serves that endpoint from a different host,
add "keycloak.corp.internal" to `sso.additional_endpoint_hosts` in the auth file

IdP の構成によっては、複数のホストからエンドポイントを提供するのが正当な場合もあります。オンプレミスでよくある例は hostname-backchannel-dynamic=true を設定した Keycloak です。この場合、token_endpoint と jwks_uri は、CLI が接続に使用した内部ホスト名に書き換えられます。追加のホストが意図したものであることを IdP 自体の設定で確認できた場合に限り、そのホストを追加してください。

"additional_endpoint_hosts": ["keycloak.corp.internal"]

項目は host (任意のポート) または host:port の形式で指定し、大文字と小文字を区別せずに照合されます。ワイルドカードは使用できず、このチェックを無効にする方法もありません。許可リストによって TLS の要件が緩和されることはありません。発行者が https:// の場合、http:// のエンドポイントは許可リストに含めても拒否されます。ログインエラーにホスト名が表示されたからといって、そのホストを追加しないでください。そのエラーは、チェックが正しく機能している証拠です。

失効が反映される仕組み

グループによるアクセス制限は、キャッシュされた ID トークンに基づいて評価されます。そのため、IdP 側でユーザーを required_group から削除した場合 (またはユーザーを無効化した場合) 、その変更は次回のトークン更新時に反映されます。反映が最も遅くなるのは、現在の ID トークンの有効期限が切れてから、さらに 120 秒のクロックスキュー許容時間が経過した時点です。失効を迅速に反映させる必要がある場合は、このクライアントの ID トークンの有効期間を短く設定してください。リフレッシュのレスポンスに新しい ID トークンが含まれていない場合は、キャッシュされた ID トークンが引き続き利用されます。ただし、利用できるのはそのトークンの exp から最大 24 時間までです。それ以降は、IdP がリフレッシュトークンを引き続き受け付けている場合でも、ユーザーは再度サインインする必要があります。

実行中のセッションにおける再検証

Devin Desktop (またはバンドルされたエージェントを利用するその他のクライアント) の実行中、エージェントは 60 秒ごとにログイン状態を再チェックし、少なくとも 15 分に 1 回は IdP に対してトークンを強制的に更新します。チェックに失敗すると、エージェントは IDP コード付きの sso_revalidation_failed 監査イベントを記録し、新しい作業の受け付けを停止してシャットダウンします。この場合、ユーザーは再度サインインしてから再起動する必要があります。

監査対象

SSO (シングルサインオン) のアクティビティは、auth イベントとしてローカルの監査ログに記録されます。検証済みのトークンを参照できるイベントでは、すべて actor に SSO アイデンティティ (sso_issuer、sso_subject、sso_user、sso_groups) が含まれます。

`action`	記録されるタイミング
`sso_login`	ログインが完了したとき (`devin auth login` または Desktop) 。
`sso_login_denied`	IdP の応答後にログインが拒否されたとき。必須のグループに所属していない場合 (`error_code: "IDP004"`) 、または返された ID トークンが検証に失敗したか存在しない場合 (`IDP005`) が該当します。`actor` には IdP が保証したアイデンティティが含まれます。キャッシュには何も保存されません。
`sso_refresh`	IdP からトークンを更新したとき。
`sso_logout`	`devin auth logout` を実行したとき、または Desktop からサインアウトしたとき。
`sso_revalidation_failed`	実行中のエージェントがログイン状態を失い、シャットダウン処理に入ったとき。`error_code` には `IDP` コードが含まれます。

IDP エラーコード

コード	意味	対処法
`IDP001`	認証ファイルが読み取れないか、内容が無効です。	`/etc/devin/auth.json` (または `DEVIN_AUTH_FILE` で指定したパス) を修正してください。問題のあるフィールドはエラーメッセージに示されます。
`IDP002`	設定済みの発行者に対するキャッシュ済みのログイン情報がありません。	`devin auth login` を実行してください。
`IDP003`	ログインが無効または期限切れで、バックグラウンドでの自動更新にも失敗しました (IdP が `invalid_grant` レスポンスを返した場合を含む) 。	`devin auth login` を再度実行してください。
`IDP004`	ログインは完了していますが、ユーザーが `required_group` のメンバーではありません。	IdP 側でユーザーをグループに追加するか、`required_group` / `groups_claim` の設定を修正してください。
`IDP005`	IdP に到達できないか、IdP がエラーを返しました。	ネットワークの疎通、TLS の信頼設定 (`DEVIN_CA_BUNDLE`) 、IdP 側のログをチェックしてください。
`IDP006`	ローカルの SSO (シングルサインオン) トークンキャッシュが読み取れないか、形式が不正であるか、現在のユーザー専用 (非公開) になっていません。	`devin auth login` を実行してください。再ログインするとキャッシュが作り直されます。

エラーコードの一覧はエラーコードページをご覧ください。

​認証ファイルを作成する

​IdP にクライアントを登録する

​サインイン

​ステータスの確認とサインアウト

​CLI が検証する内容

​検出されたエンドポイントは発行者と同じオリジンである必要がある

​失効が反映される仕組み

​実行中のセッションにおける再検証

​監査対象

​IDP エラーコード

認証ファイルを作成する

IdP にクライアントを登録する

サインイン

ステータスの確認とサインアウト

CLI が検証する内容

検出されたエンドポイントは発行者と同じオリジンである必要がある

失効が反映される仕組み

実行中のセッションにおける再検証

監査対象

IDP エラーコード