auth-md

auth-md

auth.md プロトコルを生成、検証、解説します。このオープン標準を使うと、AI エージェントはサインアップフォームを使わずに、ユーザーに代わってサービスに登録できます。

---

プロトコルの概要

auth.md は、サービスのルート（通常は https://service.com/auth.md）で公開される Markdown ファイルで、エージェントに登録方法を指示します。人間が読めるドキュメントであると同時に、エージェントが検出できるランタイムアーティファクトとして機能します。

このプロトコルは、Authorization Server のメタデータに agent_auth ブロックを追加することで、RFC 9728（OAuth 2.0 Protected Resource Metadata）を拡張します。登録時に identity_assertion（サービス署名付き JWT）が返され、エージェントはこれを /oauth2/token で交換して access_token を取得します。次の 3 つの登録方法に対応しています。

フロー	仕組み	使用する場面
identity_assertion	プロバイダーがユーザーの本人性を証明する ID-JAG（auth_time を含む）に署名します。サービスは JWKS を検証して identity_assertion を返します。エージェントはこれを /oauth2/token で交換します。	サービスが OIDC/SAML から JIT プロビジョニングを行い、登録時の手間をなくしたい場合。
service_auth	メールアドレスのヒントとブラウザーを使った手順です。エージェントは user_code と verification_uri を受け取ります。ユーザーがサインインしてコードを入力し、エージェントは /oauth2/token をポーリングします。	ID-JAG を発行できないプラットフォーム上のエージェントが、信頼リストなしでセルフサービスを利用する場合。
anonymous	事前に本人確認を行いません。要求時のスコープを付与した identity_assertion が即座に返されます。スコープをアップグレードするための遅延クレームは任意です。	エージェントがすぐに基本アクセスを必要とし、人間による所有者との紐付けを後回しにする場合。

プロトコルのエンドポイント

エンドポイント	目的
/.well-known/oauth-protected-resource	検出 — リソースのメタデータ（RFC 9728）
/.well-known/oauth-authorization-server	検出 — agent_auth ブロックを含む AS メタデータ
POST /agent/identity	登録 — type フィールドに応じて処理を振り分けます
POST /agent/identity/claim	クレームの開始（anonymous の遅延クレーム、または期限切れの user_code の再発行）
POST /oauth2/token	トークン交換（JWT ベアラーグラント）とクレームのポーリング（クレームグラント）
POST /oauth2/revoke	認証情報レイヤーでの失効（RFC 7009）
events_endpoint	登録レイヤーでの失効（SET を受信、RFC 8935）

トークンのライフサイクル

登録時に access_token が直接返されることはありません。フローは次のとおりです。

1. 登録 → identity_assertion（サービス署名付き JWT。有効期限までは再利用可能）
2. 交換 → grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer を指定して POST /oauth2/token を呼び出し → access_token
3. 更新 → access_token の期限が切れたら、同じ identity_assertion を再交換
4. アサーションの期限切れ → 登録から再開（Step 3）

クレーム手順（v2 — ブラウザーを使用）

クレーム手順では、RFC 8628 形式のデバイス認可を使用します。

1. 登録時に claim ブロック内の user_code と verification_uri が返されます
2. エージェントがその両方をユーザーに提示します
3. ユーザーが verification_uri を開いてサービスにサインインし、6 桁のコードを入力します
4. エージェントが grant_type=urn:workos:agent-auth:grant-type:claim と claim_token を指定して POST /oauth2/token をポーリングします
5. 成功すると、access_token と新しい identity_assertion が返されます

---

操作モード

パラメーター	デフォルト	説明
mode	generate	generate = auth.md とメタデータを作成、validate = 既存の auth.md を検証、explain = プロトコルを解説
validation_level	basic	basic = 構造、フィールド、一貫性をオフラインで確認、full = basic に加えてエンドポイントをライブで取得
flows	all	含めるフロー：identity_assertion、service_auth、anonymous、all
role	app	視点：app = 登録を受け付けるサービス、provider = ID-JAG を発行するプラットフォーム

---

ワークフロー：生成

1. コードベースをスキャンする

次の項目を確認します。

• 既存の API ルートと認証パターン
• 定義済みのスコープ／権限
• フレームワーク（Express、Django、Rails、FastAPI、NestJS など）
• ベース URL と認証サーバー URL の設定
• 既存の認証ミドルウェア
• ユーザーモデルとプロビジョニングの仕組み

2. 推測できないことだけをユーザーに尋ねる

• サポートするフロー（identity_assertion、service_auth、anonymous、またはその組み合わせ）
• （anonymous の場合）クレーム前とクレーム後のスコープ
• 信頼するエージェントプロバイダーと信頼リストのポリシー（identity_assertion の場合）
• サービスですでに JIT プロビジョニングを行っているか、手動オンボーディングが必要か
• idJagMaxAuthAgeSeconds の値（デフォルト：3600）
• 希望するレート制限ポリシー

3. 成果物を生成する

次の3つの成果物を作成します。

a) auth.md — プロトコルテンプレート（references/protocol-template.md を参照）に沿った Markdown ファイル。次の内容を含める必要があります。

• エージェントに向けたタイトルと導入文
• ステップ1 — 検出（2ホップ：PRM → AS メタデータ）
• ステップ2 — 方法を選択（判断ツリー）
• ステップ3 — 登録（サポートする各方法のサブセクション）
• ステップ4 — クレームの手続き（service_auth、またはクレームを伴う anonymous の場合）
• ステップ5 — アサーションを交換（jwt-bearer グラントを使った POST /oauth2/token）
• ステップ6 — access_token を使用
• エラー（該当するすべてのコードを含む完全な表）
• 失効（2つのレイヤー）

b) oauth-protected-resource.json — resource_name と resource_logo_uri を含む /.well-known/oauth-protected-resource 用の JSON

c) oauth-authorization-server.json — 次の項目を含む /.well-known/oauth-authorization-server 用の JSON：

• issuer、token_endpoint、revocation_endpoint、grant_types_supported
• identity_endpoint、claim_endpoint、events_endpoint を含む完全な agent_auth ブロック

4. 実装ガイダンスを生成する

次の内容を含む「Next Steps」セクションを作成します。

• ドメインルートで auth.md を配信する方法
• well-known パスでメタデータを配信する方法
• 401 レスポンスに WWW-Authenticate ヘッダーを追加する方法
• エンドポイントの実装ガイダンス（依頼がない限り、フレームワーク固有のコードは生成しない）
• /oauth2/token でのトークン交換の実装
• クレームページのホスティング（verification_uri → ログイン → コード入力 → 確認）
• 推奨するレート制限の設定
• 推奨する監査イベント
• セキュリティ上の考慮事項（トークンのハッシュ化、auth_time の検証、リプレイ保護、claim_token の取り扱い）

5. エージェントプロバイダー向けガイドを生成する（role=provider の場合）

ユーザーがエージェントプロバイダー（アプリではない）の場合、次の内容を生成します。

• auth_time を含む、オーディエンス固有の ID-JAG を発行する方法
• トークン構造（必須および任意のクレームを含むヘッダーとペイロード）
• JWKS の公開方法
• オプション：CIMD（Client ID Metadata Document）の公開方法
• 失効の実装方法（events_endpoint への POST SET）
• ID をアサートする前にユーザーに同意を提示する方法（resource_name + resource_logo_uri を使用）

---

ワークフロー：検証

1. auth.md を読み込む

ローカルのファイルパスまたは URL から読み込みます。

2. 指定されたレベルで検証を実行する

基本（オフライン）：

• 必須の見出し（ステップ1～6、Errors、Revocation）がすべて存在する
• 少なくとも1つのフローが記述されている
• リクエスト／レスポンスの形式を示すフェンス付きコードブロック内の JSON が有効である
• AS メタデータに identity_endpoint、token_endpoint、grant_types_supported が含まれている
• 標準エラーコードを含むエラー表がある
• 整合性：本文中のフローがメタデータ JSON の identity_types_supported と一致している
• 未置換のプレースホルダーがない

完全（ライブ）：

• 基本チェックをすべて満たし、さらに以下を満たす：
• 宣言されたベース URL から /.well-known/oauth-protected-resource を取得する
• AS メタデータに agent_auth ブロックがあることを確認する
• /.well-known/oauth-authorization-server を取得して整合性を確認する
• identity_endpoint、token_endpoint、revocation_endpoint が応答することを確認する（400／401／422 は許容し、404／405 は拒否する）
• API が resource_metadata を含む WWW-Authenticate を付けて 401 を返すことを確認する

3. 結果を報告する

カテゴリごとに、各ルールを✅／❌で示すチェックリスト：

• 構造 — 見出しと順序
• フィールド — JSON の必須フィールド
• 一貫性 — 説明文とメタデータ間の相互参照
• 形式 — 有効な JSON、有効な HTTP、プレースホルダーがないこと
• エンドポイント（フルのみ）— 到達可能性と正しい応答

重大度を含めます：🔴 エラー（エージェントが動作しなくなります）、🟡 警告（エクスペリエンスが低下します）、🟢 情報（提案）。

完全なルールセットについては、references/validation-rules.md を参照してください。

---

ワークフロー：説明

ユーザーが生成や検証をせずにプロトコルを理解したい場合：

1. ユーザーが知りたいこと（概要、特定のフロー、特定のエンドポイント、セキュリティなど）を特定します
2. 上記のプロトコルのコンテキストとリファレンスを使って説明します
3. 役立つ場合は、テキストベースのシーケンス図を使用します
4. 関連する場合は、公式ドキュメントを案内します

---

ユーザーの照合と JIT プロビジョニング

identity_assertion フローでは、登録がどのサービスユーザーを表しているかを判定する必要があります。推奨される照合順序：

1. 委任レコードの照合 — (iss, sub) の委任記録がある場合は、同じユーザーにルーティングします
2. 確認済みメールアドレスの照合 — 同じ確認済みメールアドレスを持つユーザーが存在するものの、(iss, sub) の委任がない場合 → ユーザーにリンクを確認してもらうためのクレームブロックを含めて interaction_required（401）を返します
3. 確認済み電話番号の照合 — 同じパターンを適用します
4. 一致なし → JIT — プロビジョニングポリシーに従って新しいユーザーを作成するか、拒否します

確認済みメールアドレスも確認済み電話番号もない ID-JAG は拒否してください。照合の根拠がありません。

---

レート制限

/agent/identity エンドポイントは、匿名登録では認証なしで利用できます。次の2段階を実装してください：

1. IP ごと（最初に確認）— 1つの送信元がテナントの予算を使い切るのを防ぎます。デフォルト：匿名は毎時5回、identity_assertion は毎時60回。
2. テナントごと（2番目に確認）— IP をまたいだ全体上限です。デフォルト：匿名は毎時100回、identity_assertion は毎時1000回。

/oauth2/token のポーリングにもレート制限を設けてください。クレームブロックの interval を適用し、速すぎる場合は slow_down で拒否します。

---

推奨される監査イベント

イベント	発生時	データ
registration.created	POST /agent/identity が成功したとき	registration_id, registration_type, iss, sub
registration.interaction_required	401 interaction_required	registration_id, iss, sub, matched_user_id
registration.login_required	401 login_required	iss, sub, auth_time, max_age
claim.initiated	/agent/identity/claim が呼び出されたとき	registration_id, email
claim.completed	ユーザーが正しい user_code を送信したとき	registration_id, claimed_by_user_id
claim.expired	user_code の有効期間または登録が期限切れになったとき	registration_id
token.exchanged	/oauth2/token の jwt-bearer が成功したとき	registration_id, access_token_id
token.revoked	/oauth2/revoke が呼び出されたとき	access_token_id
registration.revoked	events_endpoint で SET が処理されたとき	registration_id, iss, sub

---

セキュリティに関する考慮事項

• auth_time の検証 — ID-JAG では auth_time が必須です。サービスは idJagMaxAuthAgeSeconds に照らして検証します。古すぎる場合は login_required（401）を返します。エージェントはプロバイダーでユーザーに再認証してもらう必要があります。
• claim_token の取り扱い — 登録レスポンスで一度だけ返されます。エージェントはセレモニーの間だけメモリ上に保持します。ステップ 4 の完了後は永続化しないでください。
• トークンのハッシュ化 — claim_token はベアラーシークレットです。サーバー側には SHA-256 ハッシュのみを保存してください。
• 同意 UX — ID を表明する前に、PRM の resource_name と resource_logo_uri をユーザーに提示してください。これはユーザーが同意できる唯一の機会です。
• 2 層の取り消し — クレデンシャル層（エージェントから呼び出し可能、/oauth2/revoke。1 つの access_token を無効化）と登録層（プロバイダー起点の SET を events_endpoint で受信し、委任全体を解除。identity_assertion、派生トークン、登録、クレームハンドルをすべて解除するものであり、トークンだけではありません。サンプル #21 を参照）。
• リプレイ保護 — jti の値を、exp - iat ＋クロックスキュー（通常 6 分）以上の TTL でキャッシュしてください。
• CIMD の解決 — client_id が URL の場合は、Client ID Metadata Document として取得し、jwks_uri を検証してください。
• 一括取り消し — テナントの未失効な identity_assertion をすべて取り消すための、運用者向けの仕組みを用意してください。

---

エラーコードのリファレンス

コード	場所	意味
anonymous_not_enabled	/agent/identity	サービスは匿名アクセスを受け付けません
service_auth_not_enabled	/agent/identity	service_auth が無効です
issuer_not_enabled	/agent/identity	プロバイダーが信頼リストにありません
invalid_request	/agent/identity	Body／claim／署名／jti／aud に問題があります
interaction_required（401）	/agent/identity	ID-JAG に一致するアカウントがありますが、委任がありません。クレームが必要です
login_required（401）	/agent/identity	auth_time が古すぎます。プロバイダーで再認証してください
invalid_claim_token	/agent/identity/claim	トークンが誤っているか、有効期限が切れています
claimed_or_in_flight	/agent/identity/claim	すでにクレーム済みか、エンドポイントが誤っています
claim_expired	/agent/identity/claim	登録の有効期限が切れています
invalid_grant	/oauth2/token	アサーションの有効期限が切れているか、取り消されています
invalid_client	/oauth2/token	client_id が認識されません
unsupported_grant_type	/oauth2/token	jwt-bearer または claim grant ではありません
authorization_pending	/oauth2/token（claim）	ユーザーがセレモニーを完了していません
expired_token	/oauth2/token（claim）	user_code の有効期間が終了しました
slow_down	/oauth2/token（claim）	ポーリングが速すぎます
rate_limited（429）	任意	待機してから再試行してください

---

エージェント対応状況スキャナーのチェック

isitagentready.com スキャナーは、auth.md を authMd チェックとして検証します。合格条件は次のとおりです。

1. /auth.md がサイトのルートから HTTP 200 で提供される
2. コンテンツが Markdown で、H1 見出しに「auth.md」を含む
3. OAuth Protected Resource Metadata（/.well-known/oauth-protected-resource）を任意で検証
4. Authorization Server メタデータ（/.well-known/oauth-authorization-server）を任意で検証

最低限のチェックに合格するには：

# auth.md

This service accepts AI agent registrations.

## Authentication

Agents can register via POST /agent/identity with a valid ID-JAG.
See below for supported methods.

満点（すべてのメタデータ）を取得するには：

• 適切な見出しを含む /auth.md を提供する
• resource、resource_name、resource_logo_uri、authorization_servers、scopes_supported、bearer_methods_supported: ["header"] を含む /.well-known/oauth-protected-resource を公開する
• issuer、token_endpoint、revocation_endpoint、grant_types_supported と、skill、identity_endpoint、claim_endpoint、events_endpoint、登録方法を含む agent_auth ブロックを備えた /.well-known/oauth-authorization-server を公開する

スキャンコマンド：

curl -s -X POST 'https://isitagentready.com/api/scan' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://YOUR-DOMAIN/","enabledChecks":["authMd"]}' | jq '.checks.discovery.authMd'

---

品質チェックリスト

出力を提出する前に、以下を確認してください。

• 生成された auth.md に必須のすべての手順（1～6）、エラー、および失効処理が含まれている
• AS メタデータに issuer、token_endpoint、revocation_endpoint、grant_types_supported が含まれている
• agent_auth ブロックに identity_endpoint、claim_endpoint、events_endpoint が含まれている
• identity_types_supported がユーザーが選択したフローと一致している
• scopes_supported がコードベースで確認できる実際の API スコープを反映している
• ベース URL が auth.md とメタデータ JSON の間で一致している
• エラーコードの表に、サポート対象のフローに関する標準コードがすべて含まれている
• 手順 5 で、/oauth2/token における jwt-bearer グラントを使用したトークン交換が説明されている
• 失効のセクションで両方のレイヤー（資格情報と登録）が説明されている
• 置換されていないプレースホルダー値（{{...}}、<your-...>、[YOUR_...]）が残っていない
• 検証レポートで、要求されたレベルのすべてのルールが網羅されている
• レート制限が記載されている（/oauth2/token のポーリングを含む）
• セキュリティに関する考慮事項が含まれている（auth_time、claim_token、同意 UX）
• role=provider の場合：auth_time を含む ID-JAG の構造が説明されている

---

参考資料

• references/protocol-template.md — すべてのセクションとプレースホルダーを含む auth.md の完全なテンプレート
• references/validation-rules.md — エラーメッセージと重大度を含む検証ルール一式
• references/metadata-schema.md — PRM、AS メタデータ、ID-JAG、identity_assertion の JSON スキーマ
• references/example-auth-md.md — 完全な auth.md ファイルの動作する例（Acme Notes）
• references/implementation-guide.md — トークン交換、クレームのセレモニー、失効処理、セキュリティに関するサーバー側の実装ガイド

---

プロトコルに関する知識の更新

このスキルには、auth.md プロトコル仕様（v2、2026 年 6 月）のスナップショットが含まれています。可能な場合は、次の場所から最新版を取得してください。

• スキルホームとドキュメントハブ：https://auth-md.com
• 仕様：https://raw.githubusercontent.com/workos/auth.md/refs/heads/main/AUTH.md
• ドキュメント概要：https://workos.com/auth-md/docs
• アプリガイド：https://workos.com/auth-md/docs/apps
• エージェントプロバイダーガイド：https://workos.com/auth-md/docs/agent-providers
• ファイルの構成：https://workos.com/auth-md/docs/auth-md

取得に失敗した場合は、同梱の references/ を信頼できる情報源として使用してください。