送信者制約を設定する

Auth0 テナントで送信者制約を設定する方法の概要。

送信者拘束 は、アクセストークンと リフレッシュトークン を、それらを取得した特定のクライアントアプリケーションに暗号学的に結び付ける OAuth 2.0 および OpenID Connect (OIDC) のセキュリティメカニズムであり、トークンの盗難や不正利用を防ぎます。

Auth0 は、mTLS による送信者拘束と Demonstrating Proof-of-Possession (DPoP) をサポートしています。クライアントアプリケーションで送信者拘束を有効にする場合は、API 呼び出し先の リソースサーバー に対しても必ず適用する必要があります。

Auth0 で送信者拘束を設定するには、次の設定が必要です。

• クライアントアプリケーションで送信者拘束を設定する
• リソースサーバーで送信者拘束を設定する

​

仕組み

アクセストークン は、クライアントアプリケーションとリソースサーバーで送信者拘束をどのように設定しているかに応じて、Auth0 で送信者拘束されます。

1. 要求された audience: token request で、要求された audience が /userinfo のみか、/userinfo endpoint でのみ使用することを意図しているか、または openid scope も要求した場合に /userinfo を含む可能性があるカスタム API かによって、アクセストークンが送信者拘束されるかどうかが決まります。

2. クライアントアプリケーション: クライアントアプリケーションで送信者拘束を required に設定しているかどうか。

3. リソースサーバー: リソースサーバーで送信者拘束を設定しているかどうか。

   1. none: リソースサーバーで送信者拘束を設定していません。
   2. allowed: 送信者拘束方式を設定することで、リソースサーバーで送信者拘束を有効にしています。
   3. required: リソースサーバーで送信者拘束を必須として設定しており、アクセストークンはアプリケーションに送信者拘束されている必要があることを意味します。送信者拘束は、すべてのアプリケーションまたはパブリックアプリケーションのみに対して必須にできます。送信者拘束方式の設定が必要です。

送信者拘束方式として mTLS を使用する場合、送信者拘束は常にすべてのアプリケーションで必須になります。mTLS はパブリックアプリケーションをサポートしていないため、mTLS の送信者拘束をパブリッククライアントのみに限定することはできません。

• Proof-of-Possession: token request で、クライアントアプリケーションが proof-of-possession アサーションを送信したかどうか。

  • mTLS 送信者拘束: TLS ハンドシェイク中に、クライアントが特定の秘密キー (client certificate に関連付けられたもの) を正常に提示することで、proof of possession が示されます。
  • DPoP: クライアントが自身の秘密キーで暗号学的に署名して DPoP Proof JWT を作成し、関連するアクセストークンを使用するすべての request の DPoP HTTP header に DPoP Proof JWT を含めることで、proof of possession が実現されます。

次の表は、さまざまなクライアント request parameter と Auth0 リソースサーバーの設定に基づいて、アクセストークンがどのように発行されるか、および送信者拘束されるかどうかを示しています。

要求された audience の種類	クライアントで PoP が必須か	クライアントから Proof-of-Possession (PoP) が送信されたか	Auth0 リソースサーバーポリシー: None	Auth0 リソースサーバーポリシー: Allowed (必須ではない)	Auth0 リソースサーバーポリシー: Required
Userinfo のみ	いいえ	いいえ	発行される、送信者拘束なし	N/A	N/A
Userinfo のみ	いいえ	はい	発行される、送信者拘束あり	N/A	N/A
Userinfo のみ	はい	いいえ	発行されない	N/A	N/A
Userinfo のみ	はい	はい	発行される、送信者拘束あり	N/A	N/A
カスタム audience (Userinfo を含む場合あり)	いいえ	いいえ	発行される、送信者拘束なし	発行される、送信者拘束なし	発行されない
カスタム audience (Userinfo を含む場合あり)	いいえ	はい	発行される、送信者拘束なし	発行される、送信者拘束あり	発行される、送信者拘束あり
カスタム audience (Userinfo を含む場合あり)	はい	いいえ	発行されない	発行されない	発行されない
カスタム audience (Userinfo を含む場合あり)	はい	はい	発行されない	発行される、送信者拘束あり	発行される、送信者拘束あり

​

クライアントアプリケーションの送信者制約を設定する

クライアントアプリケーションで送信者制約を必須にすると、アクセストークンはそのアプリケーションに拘束されます。Auth0 はリクエストを検証し、トークンを要求したアプリケーションだけが、そのトークンを使って関連するリソースにアクセスできることを保証します。

クライアントアプリケーションで送信者制約を必須にするよう設定したら、リソースサーバーの設定時に、送信者制約の方式として mTLS または DPoP を指定できます。

クライアントアプリケーションの送信者制約は、Auth0 Dashboard または Management API で設定できます。

Auth0 Dashboard

1. Dashboard > Applications > Applications に移動し、設定するアプリケーションを選択します。
2. 設定 の Token Sender-Constraining までスクロールします。
3. Require Sender Constraining をオンにします。アプリケーションの送信者制約の必須設定を解除するには、オフにします。

Management API

クライアントの送信者制約を設定するには、Management API を使用します。

クライアントで送信者制約を必須にするには、クライアント設定の更新 エンドポイントに PATCH リクエストを送信します。require_proof_of_possession パラメーターを true に設定します。

curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}' \
-H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{"require_proof_of_possession": true}'

送信者制約の必須設定を解除するには、require_proof_of_possession パラメーターを false に設定します。

curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}' \
-H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{"require_proof_of_possession": false}'

​

リソースサーバーの送信者拘束を設定する

Auth0 が発行するアクセストークンは、リソースサーバー上の API にアクセスする送信者 (つまりクライアントアプリケーション) に紐付けることができます。

Auth0 Dashboard または Management API を使用して、リソースサーバーの送信者拘束を設定できます。

Auth0 Dashboard

トークンバインディングまたは送信者拘束を有効にするには、API の API Settings を設定します。

1. Auth0 Dashboard > Applications > APIs に移動します。

2. 設定する API を選択します。

3. Settings タブで、Token Sender-Constraining セクションを探します。

4. 次の項目を設定します。

   1. Sender Constraining Method:

      1. None: リソースサーバーで送信者拘束方式を有効にしません。
      2. mTLS: リソースサーバーの送信者拘束方式として mTLS を有効にします。
      3. DPoP: リソースサーバーの送信者拘束方式として DPoP を有効にします。

   2. Require Token Sender Constraining: この API に適用する送信者拘束ポリシーを選択します。

      1. Always: すべてのアプリケーションで送信者拘束を必須にします。mTLS を使用する場合に選択できるのはこのオプションのみです。
      2. For Public Applications: 公開アプリケーションでのみ送信者拘束を必須にします。このオプションは mTLS 使用時には利用できません。
      3. Never: 送信者拘束は必須ではありません。

Management API

Management API で送信者制約を有効にするには、リソースサーバーを更新する PATCH リクエストを送信します。proof_of_possession オブジェクトのパラメーターを次のように設定します。

Parameter	Description
mechanism	送信者拘束方式を設定します。指定できる値は none、mtls、dpop です。
required	必須です。true に設定すると、この API 向けにアプリケーションへ発行されるアクセストークンは、そのアプリケーションに制約されます。この要件をどのアプリケーション種別に適用するかは required_for で指定します。false に設定すると、送信者拘束は必須ではありません。
required_for	required が true の場合に、どのアプリケーション種別で送信者拘束を必須にするかを絞り込みます。指定できる値は all_clients (すべてのアプリケーション) または public_clients (公開アプリケーションのみ) です。指定しない場合のデフォルトは all_clients です。mTLS を使用する場合、有効なのは all_clients のみです。

次のコードサンプルは、リソースサーバーに mTLS 送信者制約を設定するリクエストボディの例です。mTLS では required_for に all_clients のみがサポートされます (これがデフォルトであるため、指定は不要です) 。

curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/resource-servers/{YOUR_RESOURCE_SERVER_ID}' \
-H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "proof_of_possession": {
    "mechanism": "mtls",
    "required": true
  }
}'

次のコードサンプルは、公開アプリケーションでのみ必須となる DPoP 送信者制約をリソースサーバーに設定するリクエストボディの例です。

curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/resource-servers/{YOUR_RESOURCE_SERVER_ID}' \
-H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "proof_of_possession": {
    "mechanism": "dpop",
    "required": true,
    "required_for": "public_clients"
  }
}'

次のコードサンプルは、すべてのアプリケーションで必須となる DPoP 送信者制約を設定します。all_clients はデフォルト値のため、required_for は省略できます。

curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/resource-servers/{YOUR_RESOURCE_SERVER_ID}' \
-H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "proof_of_possession": {
    "mechanism": "dpop",
    "required": true
  }
}'

次のコードサンプルは、リソースサーバーの送信者拘束を無効にします (Auth0 Dashboard で “Never” を選択するのと同じです) 。

curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/resource-servers/{YOUR_RESOURCE_SERVER_ID}' \
-H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "proof_of_possession": null 
}'