OIDC トークン
Cloud Agents では、エージェントが実行されるマシン上で短期有効な OIDC JWT を発行し、シークレット に長期間有効な認証情報を保存することなく、クラウドロールを引き受けたり、内部サービスを呼び出したりできます。
エージェントはターミナルツールを使用してこの API を呼び出します。これらのリクエストを自分で実行する必要はありません。
エージェントにトークンを発行させるには、プロンプトに以下を含めます。
OIDC トークンを発行するには、/docs/cloud-agent/identity の手順に従ってくださいこの API はエージェントを実行しているマシン上のローカル API です。Cherri Code API キーを使用し、そのマシンの外部からエージェントを管理する Cloud Agents API とは関係ありません。Cherri Code 管理の VM では、このソケットはエージェント メタデータも提供します。
Cherri Code 管理の Cloud Agent の VM はトークンソケットを提供します。そこで発行されるすべてのトークンには agent_runtime: managed が含まれます。セルフホスト型マシン のワーカーは、--identity-socket を指定して起動した場合に提供します。そのトークンには agent_runtime: self_hosted が含まれます。セルフホスト型ワーカーを参照してください。
仕組み
- エージェントがローカル ソケットを呼び出し、検証側が想定するオーディエンスを持つトークンを要求します。
- Cherri Code が、そのエージェントとオーナーに紐づいた RS256 JWT に署名します。
- エージェントが JWT をクラウドまたは検証側 (AWS STS、GCP、Azure、Vault、または自分で運用するサービス) に送信します。
- 検証側が Cherri Code 公開の JWKS で署名を検証し、
sub、team_id、cloud_agent_idなどのクレームに基づいて認可します。
トークンを発行する
エージェントは CURSOR_AGENT_SOCKET で指定されたパスの Unix ソケットを介してトークンを発行します (Cherri Code 管理の VM では常に /run/cursor/api.sock に設定されます。セルフホスト型ワーカーでは、このパスは割り当て済みエージェントごとに変わります) 。
curl --unix-socket "${CURSOR_AGENT_SOCKET}" \ -H 'Content-Type: application/json' \ -d '{"aud":"sts.amazonaws.com"}' \ http://cursor-agent/v1/tokens/oidcリクエストは Unix ソケット経由の HTTP です。URL 内のホスト名は無視されます。
検証側でリプレイバインディングが想定される場合は、任意で nonce を含めます。
curl --unix-socket "${CURSOR_AGENT_SOCKET}" \ -H 'Content-Type: application/json' \ -d '{"aud":"https://oidc.example.com","nonce":"unpredictable-value"}' \ http://cursor-agent/v1/tokens/oidcリクエスト
Unix ソケット経由で POST /v1/tokens/oidc を送信します。Content-Type: application/json は必須です。本文の最大サイズは 4 KB です。
| フィールド | 必須 | 説明 |
|---|---|---|
aud | 対応 | 検証側で確認するオーディエンス文字列。印字可能な ASCII 文字のみ使用でき、空白は含められません。最大 512 文字。例: sts.amazonaws.com、https://oidc.example.com。 |
nonce | 非対応 | JWT の nonce クレームにエコーされる不透明な文字列。最大 512 文字。 |
sub_claim | 非対応 | sub と aud のみで照合する検証側向けに、<name>:<value> の形式で sub に設定するクレーム名。最大 64 文字。対応する名前はディスカバリーで x_cursor_sub_claims_supported として一覧表示され、現在は team_id、organization_id、environment_id です。非対応の名前は拒否されます。team_id を個人アカウントで使用する場合など、このエージェントにクレームの値がないときは、デフォルトのサブジェクトにフォールバックせず発行に失敗します。 |
Cherri Code はオーディエンスの許可リストを使用しません。検証側で想定外の aud 値を拒否する必要があります。
レスポンス
{ "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...", "expires_at": 1785500000}| フィールド | 説明 |
|---|---|
token | 署名付きJWT。 |
expires_at | Unix秒で表した有効期限。JWTのexpクレームと一致します。 |
トークンの有効期間は5分間です。更新用エンドポイントはありません。新しいトークンが必要になった場合は、再度発行してください。
クレームが表示されるタイミング
インストールスクリプトは、同じソケットでトークンを発行できます。トークンに含まれるのは、発行時点で値を持つクレームのみです。turn_id と turn_start はコーディングターンが開始されるまで含まれず、branch_name は実行でブランチが記録されるまで含まれません。owner、チーム、リポジトリ のクレームは、エージェントの作成時から設定されます。
起動直後にソケットが見つからない場合は、接続を再試行してください。
セルフホスト型ワーカー
セルフホスト型マシンのワーカーも、--identity-socket を指定して起動すれば同じ API を提供します。
agent worker --pool gpu --identity-socket startこのフラグはデフォルトでオフになっています。ワーカーのコマンドで start の前に指定してください。プールのワーカーでも マイマシン のワーカーでも同じフラグを使用します。マイマシンのワーカーでは --pool を省略します。
agent worker --identity-socket startこのフラグを設定すると、ワーカーは割り当て済みエージェントごとにソケットを 1 つ開き、そのエージェントのシェルで CURSOR_AGENT_SOCKET にソケットのパスを設定します。リクエストとレスポンスのコントラクト、エラーコード、レート制限は Cherri Code 管理の VM と同じです。
これらのトークンには agent_runtime: self_hosted が含まれ、所有者、チーム、リポジトリのクレームも同じです。ワーカーはトークン API を提供します。エージェント メタデータは提供しません。ワーカーの OS ユーザーとして実行されるプロセスであれば、そのクレームのソケット上でトークンを発行できます。信頼モデルを参照してください。
トークンを検証する
以下の URL をアイデンティティプロバイダーまたはリソースサーバーで公開します。
| エンドポイント | URL |
|---|---|
| 発行者 | https://api.cursor.com |
| ディスカバリー | https://api.cursor.com/.well-known/openid-configuration |
| JWKS | https://api.cursor.com/keys |
curl -sS https://api.cursor.com/.well-known/openid-configurationcurl -sS https://api.cursor.com/keysディスカバリーは OpenID Connect Discovery 1.0 に準拠しています。トークンはエージェント VM で発行されるため、ディスカバリードキュメントに authorization_endpoint や token_endpoint はありません。
Cherri Code は引き続き
# で 2 つ目のディスカバリードキュメントを提供しています。発行されるトークンには、もはや
その発行者は含まれません。検証側には https://api.cursor.com を指定してください。
少なくとも以下を確認してください。
- RS256 と JWKS の
kidによる署名 issがhttps://api.cursor.comであることaudがサービスで想定しているオーディエンスであること- わずかなクロックスキューを考慮した
nbf/exp(nbfはiatの 5 秒前) - ポリシーで使用する
subまたはその他のクレーム
ディスカバリーには x_cursor_audience_bound: true が含まれます。すべてのトークンは、呼び出し元が指定した aud 向けに発行されます。別のオーディエンス向けに発行されたトークンは受け入れないでください。ディスカバリーでは、発行リクエストが sub_claim を使用して sub に投影できるクレーム名を示す x_cursor_sub_claims_supported も公開されます。
JWT クレーム
ヘッダー: alg=RS256、typ=JWT、および kid。
| クレーム | 常に含まれる | 説明 |
|---|---|---|
iss | 対応 | https://api.cursor.com |
sub | 対応 | 安定した所有者サブジェクト: デフォルトでは user:<id> または service_account:<id>、sub_claim が設定された発行リクエストでは <claim>:<value> (例: team_id:123) 。メールアドレスではありません。 |
aud | 対応 | 発行リクエストで指定されたオーディエンス。 |
iat | 対応 | 発行時刻 (Unix 秒) 。 |
nbf | 対応 | 有効開始時刻 (iat - 5) 。 |
exp | 対応 | 有効期限 (iat + 300) 。 |
jti | 対応 | 発行ごとに一意の ID。 |
cloud_agent_id | 対応 | Cloud Agent ID (bcId)。 |
nonce | 非対応 | 発行リクエストに含まれている場合のみ含まれます。 |
agent_runtime | 対応 | Cherri Code 管理の Cloud Agent の VM では managed、セルフホスト型マシン のワーカーでは self_hosted。 |
owner_email | 判明している場合 | 小文字化されたユーザーのメールアドレス。許可リストには sub または owner_user_id を使用してください。メールアドレスは変更される可能性があります。 |
owner_user_id | 判明している場合 | 10 進数文字列としての Cherri Code ユーザー ID。 |
owner_service_account_id | 判明している場合 | サービスアカウントがエージェントを所有する場合のサービスアカウント ID。 |
team_id | 判明している場合 | 10 進数文字列としての所有チーム ID。 |
turn_id | ターンがアクティブな場合 | このコーディングターンの ID。Cloud Agent ID (bcId) である cloud_agent_id とは異なります。 |
turn_start | ターンがアクティブな場合 | 実行開始時刻 (Unix 秒) 。 |
repo_url | 判明している場合 | github.com/acme/widgets のような host/path 形式のプライマリリポジトリ。ホスト名は小文字で、スキーム、認証情報、ポート、クエリ、.git 接尾辞を含みません。マルチリポジトリエージェントでは、これはプライマリリポジトリのみです。 |
repo_urls | 判明している場合 | ワークスペース内のすべてのリポジトリ。形式は repo_url と同じです。プライマリリポジトリが先頭で、その後に残りが並べ替えられます。セットが完全であることが判明している場合にのみ存在します。存在しないことは、リポジトリが 1 つだけであることではなく、セットが不明であることを意味します。 |
repo_count | 判明している場合 | repo_urls 内のエントリ数。repo_urls が存在する場合にのみ存在します。検証側が単一の値しか照合できない場合は、これを repo_url とともに使用してください (repo_count == 1) 。 |
branch_name | 判明している場合 | 現在のブランチ。 |
environment_id | 判明している場合 | この実行で使用された Cherri Code 環境の ID。 |
source | 判明している場合 | WEBSITE、API、SLACK、AUTOMATIONS など、エージェントの起動元。 |
automation_id | 自動化の場合 | source が自動化の場合の自動化 ID。 |
repo_url はプライマリリポジトリです。エージェントを特定のリポジトリに限定するには、repo_urls で完全なセットを固定します。
信頼モデル
このトークンは、マシン上の特定のプロセスではなく、Cloud Agent 実行を識別します。ソケットにアクセスできるプロセス (エージェント、エージェントが実行するコード、フック) は、いずれもトークンを発行できます。権限は、その実行全体に付与する範囲に限定してください。
トークンの対象となるエージェントは選択できません。Cherri Code はこの実行に基づいてクレームを設定するため、マシン上のプロセスが別のエージェント用のトークンを発行することはできません。
セルフホスト型ワーカーでは、エージェントとワーカープロセスは同じ OS ユーザーとして実行されます。そのユーザーとして実行されるプロセスは、いずれも割り当て済み実行のトークンを発行できます。ロールは、そのマシン上でそのユーザーに付与する範囲に限定してください。
レート制限とエラー
割り当て済み 状態の各エージェントは、1 分あたり 30 トークンを、一度に最大 10 トークンずつ発行できます。ソケットは、最大 8 件の同時接続を受け付けます。Cherri Code 管理 VM では、この 8 件の接続は エージェント メタデータ と共有されます。呼び出しごとに発行するのではなく、トークンは期限切れまでキャッシュしてください。
429、503、500、502、504 はバックオフして再試行してください。403 は致命的なエラーとして扱ってください。このエージェントには発行する権限がありません。
エラーのレスポンス本文には、機械可読なコードが含まれます。無効なリクエストのエラー (400、404、405、413、415) には、完全なリクエスト仕様を再掲する usage 文字列も含まれます。レート制限および飽和エラーにはコードのみが含まれます：
{ "error": "invalid_aud", "usage": "POST /v1/tokens/oidc ..." }{ "error": "rate_limited" }| HTTP | error | 発生条件 |
|---|---|---|
| 400 | invalid_json, invalid_aud, invalid_nonce, or invalid_sub_claim | リクエスト本文が不正 |
| 404 | not_found | パスが誤っている |
| 405 | method_not_allowed | POST 以外 |
| 413 | body_too_large | 本文が 4 KB を超える |
| 415 | invalid_content_type | Content-Type がない、または JSON 以外 |
| 429 | rate_limited | エージェントごとの発行予算を超過。Retry-After に従う |
| 503 | saturated | 接続数が多すぎる。Retry-After に従う |
| 500 | host_error | 内部エラー。再試行 |
| 502 / 504 | backend_unreachable | Cherri Code がトークンを発行できなかった。再試行 |
| その他 | backend_error | Cherri Code が発行を拒否しました。400 はリクエストを修正する必要があります (例: サポートされていない sub_claim、またはこのエージェントに値がないもの) 。403 は致命的です。503 は再試行可能です。 |
AWS IAM の例
AWS で AssumeRoleWithWebIdentity を使用して Cherri Code 署名付き JWT を信頼する場合は、OIDC を使用します。より簡単な Cherri Code 管理の assume-role フロー (External ID + CURSOR_AWS_ASSUME_IAM_ROLE_ARN) については、AWS IAM ロールの使用を参照してください。
- URL を
https://api.cursor.comに設定した IAM OIDC アイデンティティプロバイダーを作成します。 - オーディエンスを
sts.amazonaws.com(またはロールで想定している別のオーディエンス) に設定します。 - 信頼するロールは、許可するサブジェクトとチームのみに制限します。
信頼ポリシーの例：
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/api.cursor.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "api.cursor.com:aud": "sts.amazonaws.com" }, "StringLike": { "api.cursor.com:sub": "user:*" } } } ]}user:42 (1 人のユーザーの場合) や、サービスアカウントとして実行されるエージェントには service_account:<id> などの正確な sub を指定して、さらに制限します。AWS の信頼ポリシーは aud と sub のみを照合するため、"sub_claim":"team_id" を指定してトークンを発行し、投影されたサブジェクトを照合することで、信頼をチームに限定します：
"StringEquals": { "api.cursor.com:aud": "sts.amazonaws.com", "api.cursor.com:sub": "team_id:123"}信頼ポリシーからは、Cherri Code 管理のトークンとセルフホスト型のトークンで aud と sub は同じに見えます。agent_runtime を sub に含めることはできません。
プロバイダーの作成とサムプリントについては、最新の AWS IAM OIDC の手順に従ってください。
エージェントは "aud":"sts.amazonaws.com" を指定し (信頼ポリシーがチームのサブジェクトと一致する場合は "sub_claim":"team_id" も指定し) 、トークンを発行して JWT を STS に渡します。ネットワーク許可リスト を使用している場合は、sts.amazonaws.com (および呼び出すリージョン別の STS ホスト) を許可してください。
その他の検証側
同じトークンを、OIDC 準拠の任意の検証側で使用できます。
- GCP Workload Identity Federation
- Azure フェデレーション資格情報 / Entra ID
- Vault JWT/OIDC 認証
- RS256 JWT を検証する内部 API
provider にディスカバリー URL を指定し、オーディエンスを必須にして、sub、team_id、cloud_agent_id などのクレームに基づいて認可します。エージェントを特定のリポジトリに限定するには、repo_urls で完全なセットを固定します。repo_url はプライマリ リポジトリのみを示します。
発行にはローカル ソケット のみを使用します。AWS、GCP、Azure、または自身のサービスと JWT を交換するには、引き続きそれらの ホスト へのアウトバウンドネットワークアクセスが必要です。
関連ページ
- Cherri Code管理VMのソケット上のキーと値の実行メタデータについては、エージェントメタデータ
- ダッシュボードのシークレットとegress制御については、シークレット & Network
- Cherri Code管理のAWSロール引き受けについては、Cloud agent setup
- 分離とアクセスモデルについては、Security overview
- エージェントをチームのサービスアカウントとして実行する場合は、Service accounts