CIMD を使用してアプリケーションを登録する

Client ID Metadata Document（CIMD）を使用してアプリケーションを登録する方法を学びます。

Client ID Metadata Document (CIMD) 登録の利点やユースケース、手動および動的 CIMD の仕組みについては、CIMD の概要を参照してください。

​

前提条件

CIMDでアプリケーションを登録する前に、次の要件を満たしていることを確認してください。

​

テナントとアプリケーションの設定

CIMD クライアントとして登録できるのは、サードパーティ製アプリケーションのみです。

• API アクセスポリシーを設定する: サードパーティ製アプリケーションが API にアクセスするには、明示的なクライアントへの認可が必要です。
• 接続をドメインレベルに昇格する: ユーザーを認証できるよう、接続をドメインまたはテナントレベルで利用可能にします。これはサードパーティ製アプリケーションでは必須です。
• Resource Parameter Compatibility Profile (任意): MCP クライアントでは、テナント設定でこのプロファイルを有効にすることを推奨します。これにより、audience が指定されていない場合に resource パラメーターを確認して、認可サーバーがリソース固有のリクエスト (RFC 8707) を処理できるようになります。

​

サポートされているクライアントタイプ

Auth0 では、CIMD で次のクライアントタイプを登録できます。

• アプリケーションの種類: ネイティブアプリケーションまたは通常の Web アプリケーションである必要があります。
• サードパーティ製アプリケーション: サードパーティ製アプリケーション (is_first_party: false) である必要があり、強化されたセキュリティ制御 が適用されます。

​

サポートされる認証方式

CIMDクライアントでは、client_secret_post、client_secret_basic、client_secret_jwt など、共有対称シークレットに基づく認証方式は使用できません。

クライアントがパブリックかコンフィデンシャルかに応じて、Auth0 は CIMDクライアントに対して次の認証方式をサポートしています。

• パブリッククライアント:
  • トークンエンドポイントではクライアント認証は不要です。クライアントメタデータの token_endpoint_auth_method を none に設定してください
  • 認可フローでは Proof Key for Code Exchange (PKCE) を使用する必要があります
• コンフィデンシャルクライアント:
  • Private Key JWT 認証 のみサポートされています。クライアントメタデータの token_endpoint_auth_method を private_key_jwt に設定してください
  • 公開キーをホストするための jwks_uri を指定します。jwks_uri は、CIMD URL と完全に同一のオリジン (スキーム、ホスト、ポート) である必要があります。詳しくは、CIMD JSON 検証ルール をご覧ください。

Private Key JWT 認証 は Enterprise のお客様のみご利用いただけます。Enterprise プランの詳細については、Pricing をご確認いただくか、Auth0 Sales にお問い合わせください。

Private Key JWT 認証 を使用する手動登録の CIMDクライアントは、新しい一意の kid を持つ新しいキーペアを生成してキーローテーションを実装する 必要があります。

​

CIMD登録を有効にする

Auth0 DashboardまたはManagement APIを使用して、CIMD登録を有効にします。

Auth0 Dashboard

• CIMDサポートの有効化：テナント設定で Client ID Metadata Document Registration トグルを有効にします。これにより、Auth0認可サーバーのメタデータにCIMDのサポートが示され、クライアントは接続時にこの機能を自動的に検出できるようになります。
  • ［Settings］>［Advanced］ に移動し、 ［Settings］ セクションまでスクロールします。
  • Client ID Metadata Document Registration をオンにします。
• 動的CIMD登録のサポート：テナント設定で、 Client ID Metadata Document Registration の下にある Dynamic CIMD Registration トグルを有効にします。有効にすると、新しいクライアントは動的CIMDで自身を登録できるようになります。無効にすると、新しいクライアントは動的CIMDで自身を登録できなくなりますが、既存の動的CIMDクライアントは引き続き通常どおり動作します。

Management API

Client ID Metadata Document Registration トグルは client_id_metadata_document_supported プロパティに、 Dynamic CIMD Registration は client_id_metadata_document_dynamic_registration_supported に対応しています。いずれも PATCH /api/v2/tenants/settings エンドポイントで設定します。

client_id_metadata_document_dynamic_registration_supported を有効にするには、 client_id_metadata_document_supported が true になっている必要があります。また、 client_id_metadata_document_dynamic_registration_supported が true の間は、 client_id_metadata_document_supported を無効にできません。これらの操作を行おうとすると、次のような 400 Bad Request エラーが返されます。

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorCode": "validation_error",
  "message": "client_id_metadata_document_dynamic_registration_supported cannot be enabled when client_id_metadata_document_supported is false. Enable client_id_metadata_document_supported in the same request or beforehand."
}

テナントに動的CIMD登録の利用権限がない場合、 client_id_metadata_document_dynamic_registration_supported を設定すると 403 Forbidden エラーが返されます。

{
  "statusCode": 403,
  "error": "Forbidden",
  "errorCode": "not_entitled",
  "message": "Updating the client_id_metadata_document_dynamic_registration_supported setting is not allowed for this tenant."
}

​

CIMD を使用してアプリケーションを登録する

Auth0 でアプリケーションを作成する際は、Auth0 Dashboard または Management API を使用して、CIMD に手動で登録します。

動的 CIMD 登録が有効な場合、アプリケーションは実行時に自身の CIMD URL を介して Auth0 に登録を行います。動的 CIMD 登録を有効にするには、CIMD 登録を有効にするを参照してください。

Auth0 Dashboard

Auth0 Dashboard を使用して手動で CIMD を使用するアプリケーションを登録するには、次の手順に従います。

1. Applications > Applications に移動します。
2. Create Application > Import from URL を選択します。
3. CIMD URL を入力し、Preview を選択します。Auth0 は CIMD URL 検証ルール に従って CIMD URL を検証します。
4. CIMD URL が有効な場合、Auth0 は CIMD を読み込んで CIMD JSON 検証ルール に従って検証します。クライアントメタデータをプレビューし、検証エラーがあれば対処してください。
5. Create を選択します。

Management API

Management API を使用して手動で CIMD を使用するアプリケーションを登録するには、次の手順に従います。

1. CIMD をプレビューする: Auth0 で CIMD URL と CIMD を検証します
2. CIMD クライアントを登録する: アプリケーションを Auth0 に CIMD クライアントとして登録します

​

CIMD をプレビューする

CIMD をプレビューするには、/api/v2/clients/cimd/preview エンドポイントに POST リクエストを送信し、以下を指定します。

• external_client_id: アプリケーションの CIMD URL

/api/v2/clients/cimd/preview エンドポイントは、external_client_id とその URL にある CIMD を読み込んで検証し、クライアントメタデータと検証エラーをプレビューできるようにします。

次のリクエストでは、https://mcpserver.example.com/client.json を external_client_id として /api/v2/clients/cimd/preview エンドポイントに渡します。

Auth0 CLI

Auth0 CLI をお使いですか？まだの場合は、このコマンドを実行する前に CLI セッションのセットアップと認証 を行ってください。

auth0 api post "clients/cimd/preview" \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

cURL

curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/cimd/preview' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

成功すると、Auth0 は次のようなレスポンスを返します。

{
  "mapped_fields": {
    "external_client_id": "https://mcpserver.example.com/client.json",
    "redirect_uris": ["https://mcpserver.example.com/callback"],
    "client_name": "MCP Tool Server",
    "logo_uri": "https://mcpserver.example.com/logo.png",
    "grant_types": ["authorization_code"],
    "scope": "read write"
  },
  "validation": {
    "valid": true,
    "warnings": [
      "Grant type not supported: 'implicit'",
      "Property not supported: 'nfv_token_signed_response_alg'"
    ]
  }
}

プレビューした external_client_id でクライアントがすでに登録されている場合、レスポンスには client_id と external_metadata_created_by も含まれます。

{
  "mapped_fields": { "..." },
  "validation": { "valid": true, "violations": [], "warnings": [] },
  "client_id": "YOUR_CLIENT_ID",
  "external_metadata_created_by": "client"
}

external_metadata_created_by は、既存のクライアントがどのように登録されたかを示します。

値	説明
client	アプリケーションが実行時に自身の CIMD URL を使用して動的に自己登録しました。
admin	テナント管理者が CIMD URL を使用してアプリケーションを手動で登録しました。

​

CIMD クライアントを登録する

クライアントメタデータを確認したら、/api/v2/clients/cimd/register エンドポイントに POST リクエストを送信し、以下を指定します。

• external_client_id: アプリケーションの CIMD URL

/api/v2/clients/cimd/register エンドポイントは、CIMD アプリケーションを登録します。同じ external_client_id を持つ手動 CIMD クライアントがすでに存在する場合、Auth0 は新しいクライアントを作成せず、既存のクライアントを更新します。同じ external_client_id を持つ動的 CIMD クライアントがすでに存在する場合は、リクエストが 409 Conflict エラーで失敗します。

次のリクエストでは、https://mcpserver.example.com/client.json を external_client_id として /api/v2/clients/cimd/register エンドポイントに渡します。

Auth0 CLI

auth0 api post "clients/cimd/register" \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

cURL

curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/cimd/register' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

成功すると、Auth0 は次のようなレスポンスを返します。

Location: /api/v2/clients/YOUR_CLIENT_ID
{
  "client_id": "YOUR_CLIENT_ID",
  "mapped_fields": {
    "external_client_id": "https://mcpserver.example.com/client.json",
    "redirect_uris": ["https://mcpserver.example.com/callback"],
    "client_name": "MCP Tool Server",
    "logo_uri": "https://mcpserver.example.com/logo.png",
    "grant_types": ["authorization_code"],
    "scope": "read write"
  },
  "validation": {
    "valid": true,
    "warnings": [
      "Grant type not supported: 'implicit'",
      "Property not supported: 'nfv_token_signed_response_alg'"
    ]
  }
}

​

クライアントメタデータを更新する

手動CIMDクライアントと動的CIMDクライアントでは、クライアントメタデータの更新方法が異なります。

手動CIMDクライアント

手動CIMDクライアントでは、クライアントメタデータを手動で更新できます。Auth0がCIMDから最新のクライアントメタデータを取得するので、内容をプレビューしてから保存できます。

クライアントメタデータを更新すると、Auth0はホストされているCIMDの値に合わせてapp_typeとgrant_typesを更新します。CIMDフィールドの詳細については、「CIMD JSON検証ルール」をお読みください。

Auth0 Dashboardで以下を行います。

1. ［Applications (アプリケーション) ］>［Applications (アプリケーション) ］に移動して、CIMDクライアントを選択します。
2. 右上隅にある［Refresh Client Metadata (クライアントメタデータの更新) ］を選択します。
3. ［Refresh Preview (プレビューの更新) ］を選択して、CIMD内の最新のクライアントメタデータをプレビューします。バリデーションの警告やエラーがあれば確認します。
4. ［Save (保存) ］を選択します。

動的CIMDクライアント

動的CIMDクライアントでは、次のような場合にAuth0が最新のCIMDドキュメントを自動的に取得します。

• 初回の検出時に、クライアントがAuth0にOAuthリクエストを送信したとき
• CIMDのキャッシュコピーが存在しないとき
• redirect_uriの不一致など、OAuthリクエストの一部がバリデーションに失敗したとき

手動CIMDではテナント管理者がメタデータの更新を確認・承認しますが、動的CIMDでは、更新されたメタデータとキーの変更が自動的に再取得・検証され、そのクライアントを使用するすべてのテナントに適用されます。テナントごとの操作は必要ありません。

頻繁に使用されるクライアントは、情報が古くなる前にバックグラウンドで定期的に更新されます。そのため、アクティブなユーザーがメタデータのリアルタイム取得を待たされ、ログインに余計な時間がかかることはありません。使用頻度の低いクライアントは、必要になった時点でのみ更新されます。

​

メタデータとキーの更新タイミングの分離

CIMDメタデータ (名前、リダイレクトURIなど) と署名鍵 (JWKS) は、 それぞれ異なるスケジュールで更新されます。キーはメタデータよりもはるかに頻繁にローテーションされるためです。 これにより、キーをローテーションしてもメタデータ全体を不必要に再取得することはなく、 その逆も同様です。

​

キーの自動解決

トークンの検証中に必要な署名鍵 (kid) が見つからない場合、Auth0は 手動での更新を求めることなく、クライアントのjwks_uriから最新のキーを オンデマンドで自動的に取得します。

​

障害時の処理

クライアントのメタデータURLやキーに一時的にアクセスできなくなったり、無効になったりした場合、 Auth0はリクエストのたびにすぐ再試行するのではなく、自動的にバックオフします。 検証済みのメタデータを正常に取得できたにもかかわらず、 リクエストの一部が依然として無効な場合は、Auth0はドキュメントを再取得せずに その認可リクエストを失敗させます。

​

CIMDクライアントを取得する

CIMDクライアントを取得するには、GET リクエストを /v2/clients/{clientId} エンドポイントに送信します。{clientID} は、CIMDクライアントに割り当てられた Auth0 生成のクライアント ID です。

Auth0 CLI

auth0 api get "clients/YOUR_CLIENT_ID"

cURL

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json'

または、external_client_id もしくは CIMD URL を、/v2/clients エンドポイントのクエリパラメーターとして渡します:

Auth0 CLI

auth0 api get "clients" \
  -q "external_client_id=https://mcpserver.example.com/client.json"

cURL

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients?external_client_id=https://mcpserver.example.com/client.json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json'

成功すると、Auth0 は external_client_id、name、callbacks、token_endpoint_auth_method、external_metadata_created_by、external_metadata_status などのフィールドを含む CIMD クライアント設定を含んだレスポンスを返します。

​

CIMDメタデータのステータス

すべてのCIMDクライアントには external_metadata_status フィールドが含まれています。このフィールドは、Auth0がクライアントのホストされたメタデータドキュメントを解決できたかどうかを示します。

値	説明
available	メタデータドキュメントは解決済みです。手動CIMDクライアントでは、メタデータの更新タイミングをテナント管理者が制御するため、常に available が返されます。動的CIMDクライアントの場合、available はある時点での解決状況を示すものであり、返されるフィールドが最新バージョンであることを保証するものではありません。Auth0は、リクエストのたびにメタデータを再取得するのではなく、直近にキャッシュされたコピーを返す場合があります。
unavailable	Auth0はクライアントのメタデータドキュメントを解決できませんでした。たとえば、ホストされたCIMD URLに一時的に到達できない場合や、無効なコンテンツが返される場合などが該当します。この状態の間は、name と app_type のみが最後に取得された (古い) 値のまま返され、メタデータに由来するその他のフィールドは省略されます。メタデータが再び解決可能になるまで、このクライアントの認証リクエストは失敗します。

external_metadata_status: "unavailable" の動的CIMDクライアントは、メタデータURLに再び到達できるようになれば自動的に回復します。Auth0が以降の認証リクエスト時にメタデータを自動で再解決するため、手動での操作は必要ありません。ステータスが長期間 unavailable のままの場合は、回復を待ち続けるのではなく、クライアントの削除を検討してください。

CIMDメタデータのステータスをトラブルシューティングするには、/api/v2/clients/cimd/preview エンドポイントに POST リクエストを送信します。URLには到達できてもCIMDメタデータドキュメントが無効な場合は、Auth0からバリデーションエラーが返されます。

​

CIMD クライアントを更新する

登録済みの CIMD クライアントについて、Auth0 データベース内のフィールドを更新できます。Auth0 内の CIMD クライアントを更新しても、アプリケーションのドメインでホストされている CIMD には自動的に反映されません。

CIMD クライアントで更新できるのは、次のフィールドのみです。動的 CIMD クライアントにはさらに制限があり、app_type、description、grant_types、name は更新できません。

Field	Description
app_type	Auth0 のアプリケーションの種類です。CIMD では、これは application_type からマッピングされ、native (ネイティブアプリ用) または regular_web (Web アプリ用) のみ使用できます。
grant_types	許可される OAuth 2.0 のグラントタイプです。CIMD では、authorization_code と refresh_token のみに制限されます。その他のタイプは、マッピング時に除外されます。
jwt_configuration.alg	ID トークンの署名に使用するアルゴリズムです。厳格なサードパーティークライアントとして、CIMD アプリケーションは通常、RS256、RS512、PS256 などの安全な非対称アルゴリズムに制限されます。
description	クライアントの自由記述の説明です。CIMD メタデータから直接マッピングされ、最大 140 文字までです。
oidc_conformant	厳格なサードパーティークライアントでは有効になっている必要があります。これにより、クライアントが OIDC 仕様に準拠することが保証され、通常、CIMD クライアントでは変更できません。
allowed_origins	Cross-Origin Resource Sharing (CORS) で許可される URL の一覧です。通常はブラウザベースのアプリケーションで使用されます。
web_origins	Web ベースのフロー (例: Silent Authentication) で許可される URL の一覧です。
refresh_token.*	rotation_type、leeway、各種有効期間設定など、リフレッシュトークンの動作に関する設定です。これらは、リフレッシュトークンの有効期間や、使用時にローテーションするかどうかを制御します。
organization_*	usage、require_behaviour、discovery_methods、default_organization など、組織固有フローに関する設定です。これらは、クライアントが Auth0 Organizations とどのように連携するかを決定します。
client_metadata	標準の Auth0 プロパティにマッピングされない、クライアントに関する追加情報を保存するための任意のキーと値のペアです。
require_proof_of_possession	クライアントがキーの所持証明を提示する必要があるかどうかを示します。多くの場合、DPoP または mTLS とともに使用されます。

CIMD クライアントを更新するには、/v2/clients/{clientId} エンドポイントに PATCH リクエストを送信します。ここで、{clientID} は CIMD クライアントに割り当てられた Auth0 生成のクライアント ID です。

Auth0 CLI

auth0 api patch "clients/YOUR_CLIENT_ID" \
  --data '{
    "description": "This is my test CIMD client"
  }'

cURL

curl --location --request PATCH \
  'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "description": "This is my test CIMD client"
  }'

​

セキュリティ上の考慮事項

​

private_key_jwt 認証のための CIMD クライアントのキーローテーション

Private Key JWT 認証を使用する CIMD クライアントのキーを適切にローテーションするには、新しく一意の kid を持つ新しいキーペアを生成してください。秘密キーをローテーションし、同じ kid のまま新しいキーマテリアルで JWKS を更新すると、Auth0 の CIMD 登録では新しいキーは拒否され、古いキーが保持されます。これは、キーローテーションでは新しいキーを明示的に追加する必要があり、気付かないうちに置き換えられることはないようにするためです。

手動 CIMD クライアントの場合は、キーをローテーションしたら、Auth0 でキー登録も忘れずに更新してください。詳しくは、署名キーのローテーション を参照してください。

動的 CIMD クライアントの場合、手動での更新は不要です。トークンの検証時に Auth0 が署名キー (kid) を見つけられない場合は、クライアントの jwks_uri から最新のキーが自動的に取得されます。

​

動的CIMDクライアントでは認証情報がサポートされない

動的CIMDクライアントはjwks_uriから解決されたキーで認証するため、保存された認証情報レコードを持ちません。動的CIMDクライアントに対して/v2/clients/{id}/credentialsエンドポイントへPOSTリクエストを送信すると、次のエラーが返されて失敗します。

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorCode": "client_credentials_not_supported",
  "message": "Credentials of dynamically registered CIMD clients are resolved from the jwks_uri of their client ID metadata document and cannot be managed through this endpoint."
}

動的CIMDクライアントのキーをローテーションするには、そのドメインでホストされているjwks_uriドキュメントを更新します。新しいキーは、必要に応じてAuth0が自動的に取得します。動的CIMDクライアントの認証情報の読み取り、更新、削除はブロックされません。ただし、認証情報のレコードが存在しないため、これらのリクエストは、認証情報を持たないクライアントに対する場合と同じ結果になります (空のリストが返される、特定の認証情報IDに対しては404 Not Foundが返される、削除時には冪等な204 No Contentが返される) 。手動のCIMDクライアントや、その他のアプリケーションの種類のクライアントには、この制限は適用されません。