Configurer la contrainte de l’émetteur

Aperçu de la façon de configurer la contrainte de l’émetteur pour votre locataire Auth0.

La contrainte de l’émetteur est un mécanisme de sécurité d’OAuth 2.0 et d’OpenID Connect (OIDC) qui lie cryptographiquement les jetons d’accès et les jetons d’actualisation à l’application cliente précise qui les a obtenus, ce qui empêche leur vol et leur utilisation abusive.

Auth0 prend en charge la contrainte de l’émetteur mTLS et Demonstrating Proof-of-Possession (DPoP). Si vous activez la contrainte de l’émetteur pour une application cliente, vous devez aussi l’appliquer au serveur de ressources sur lequel vous effectuez des appels d’API.

Pour configurer la contrainte de l’émetteur dans Auth0, vous devez :

• Configurer la contrainte de l’émetteur pour une application cliente
• Configurer la contrainte de l’émetteur pour un serveur de ressources

​

Fonctionnement

Les jetons d’accès sont soumis à une contrainte de l’émetteur dans Auth0 selon la façon dont vous configurez la contrainte de l’émetteur pour votre application cliente et votre serveur de ressources :

1. Audience demandée : Dans une demande de jeton, le fait que l’audience demandée soit uniquement /userinfo, qu’elle soit destinée à être utilisée seulement avec le point de terminaison /userinfo, ou qu’il s’agisse d’une API personnalisée pouvant inclure /userinfo lorsque vous demandez aussi le scope openid, détermine si les jetons d’accès sont soumis à une contrainte de l’émetteur.

2. Application cliente : Le fait que vous définissiez la contrainte de l’émetteur sur required pour l’application cliente.

3. Serveur de ressources : Le fait que vous configuriez la contrainte de l’émetteur pour le serveur de ressources :

   1. none : Vous n’avez pas configuré de contrainte de l’émetteur pour le serveur de ressources.
   2. allowed : Vous avez configuré la contrainte de l’émetteur pour le serveur de ressources en définissant une méthode de contrainte de l’émetteur.
   3. required : Vous avez configuré la contrainte de l’émetteur comme obligatoire pour le serveur de ressources, ce qui signifie que les jetons d’accès doivent être liés à une application par une contrainte de l’émetteur. Vous pouvez exiger la contrainte de l’émetteur pour toutes les applications ou seulement pour les applications publiques. Nécessite une méthode de contrainte de l’émetteur.

Lorsque vous utilisez mTLS comme méthode de contrainte de l’émetteur, la contrainte de l’émetteur est toujours obligatoire pour toutes les applications. Les applications publiques ne sont pas prises en charge avec mTLS; vous ne pouvez donc pas limiter la contrainte de l’émetteur mTLS aux seuls clients publics.

• Proof-of-Possession : Le fait que l’application cliente ait envoyé une preuve de possession dans la demande de jeton :

  • contrainte de l’émetteur mTLS : La preuve de possession est démontrée par la présentation réussie, par l’application, d’une clé privée précise (associée à un certificat client) pendant la négociation TLS.
  • DPoP : La preuve de possession est établie lorsque l’application crée un JWT de preuve DPoP en le signant de façon cryptographique avec sa clé privée et inclut le JWT de preuve DPoP dans l’en-tête HTTP DPoP de chaque requête où le jeton d’accès associé est utilisé.

Le tableau suivant décrit comment les jetons d’accès sont émis et s’ils sont soumis à une contrainte de l’émetteur selon différents paramètres de demande de l’application cliente et les configurations du serveur de ressources Auth0 :

Type d’audience demandée	L’application exige une PoP ?	Proof-of-Possession (PoP) envoyée par l’application ?	Stratégie du serveur de ressources Auth0 : None	Stratégie du serveur de ressources Auth0 : Allowed (Not Required)	Stratégie du serveur de ressources Auth0 : Required
Userinfo seulement	Non	Non	Émis, sans contrainte de l’émetteur	N/A	N/A
Userinfo seulement	Non	Oui	Émis, soumis à une contrainte de l’émetteur	N/A	N/A
Userinfo seulement	Oui	Non	Non émis	N/A	N/A
Userinfo seulement	Oui	Oui	Émis, soumis à une contrainte de l’émetteur	N/A	N/A
Audience personnalisée (peut contenir Userinfo)	Non	Non	Émis, sans contrainte de l’émetteur	Émis, sans contrainte de l’émetteur	Non émis
Audience personnalisée (peut contenir Userinfo)	Non	Oui	Émis, sans contrainte de l’émetteur	Émis, soumis à une contrainte de l’émetteur	Émis, soumis à une contrainte de l’émetteur
Audience personnalisée (peut contenir Userinfo)	Oui	Non	Non émis	Non émis	Non émis
Audience personnalisée (peut contenir Userinfo)	Oui	Oui	Non émis	Émis, soumis à une contrainte de l’émetteur	Émis, soumis à une contrainte de l’émetteur

​

Configurer la contrainte de l’émetteur pour une application cliente

Lorsque vous exigez la contrainte de l’émetteur pour une application cliente, les jetons d’accès sont liés à cette application. Auth0 vérifie les requêtes pour s’assurer que seule l’application qui a demandé le jeton peut l’utiliser pour accéder à la ressource associée.

Une fois la contrainte de l’émetteur exigée pour une application cliente, vous pouvez définir la méthode de contrainte de l’émetteur, soit mTLS ou DPoP, lors de la configuration de votre serveur de ressources.

Vous pouvez configurer la contrainte de l’émetteur pour une application cliente à l’aide de l’Auth0 Dashboard ou de la Management API.

Auth0 Dashboard

1. Accédez à Dashboard > Applications > Applications. Sélectionnez l’application que vous souhaitez configurer.
2. Sous Settings, faites défiler jusqu’à Token Sender-Constraining.
3. Activez Require Sender Constraining. Désactivez cette option pour ne plus exiger la contrainte de l’émetteur pour l’application.

Management API

Pour configurer la contrainte de l’émetteur pour une application, utilisez la Management API.

Pour exiger la contrainte de l’émetteur pour une application, envoyez une requête PATCH pour mettre à jour les paramètres de l’application. Définissez le paramètre require_proof_of_possession sur 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}'

Pour supprimer cette exigence, définissez le paramètre require_proof_of_possession sur 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}'

​

Configurer la contrainte de l’émetteur pour un serveur de ressources

Les jetons d’accès émis par Auth0 peuvent être liés à l’émetteur (c.-à-d. l’application cliente) qui doit accéder aux API d’un serveur de ressources.

Vous pouvez configurer la contrainte de l’émetteur pour un serveur de ressources à l’aide de l’Auth0 Dashboard ou de la Management API.

Auth0 Dashboard

Pour activer la liaison de jeton ou la contrainte de l’émetteur, configurez les API Settings de votre API.

1. Accédez à Auth0 Dashboard > Applications > APIs.

2. Sélectionnez l’API que vous voulez configurer.

3. Dans l’onglet Settings, repérez la section Token Sender-Constraining.

4. Configurez les éléments suivants :

   1. Méthode de contrainte de l’émetteur :

      1. None: N’activez aucune méthode de contrainte de l’émetteur pour votre serveur de ressources.
      2. mTLS: Activez mTLS comme méthode de contrainte de l’émetteur pour votre serveur de ressources.
      3. DPoP: Activez DPoP comme méthode de contrainte de l’émetteur pour votre serveur de ressources.

   2. Exiger la contrainte de l’émetteur du jeton : sélectionnez la stratégie de contrainte de l’émetteur qui s’applique à cette API :

      1. Always: Exigez la contrainte de l’émetteur pour toutes les applications. C’est la seule option offerte lorsque vous utilisez mTLS.
      2. For Public Applications: Exigez la contrainte de l’émetteur uniquement pour les applications publiques. Cette option n’est pas offerte lorsque vous utilisez mTLS.
      3. Never: La contrainte de l’émetteur n’est pas requise.

Management API

Pour activer la contrainte de l’émetteur avec la Management API, envoyez une requête PATCH pour mettre à jour le serveur de ressources. Définissez les paramètres de l’objet proof_of_possession comme suit :

Paramètre	Description
mechanism	Définit la méthode de contrainte de l’émetteur : none, mtls ou dpop.
required	Obligatoire. Lorsqu’elle est définie à true, les jetons d’accès émis à une application pour cette API seront liés à cette application. Utilisez required_for pour préciser à quels types d’applications cette exigence s’applique. Lorsqu’elle est définie à false, la contrainte de l’émetteur n’est pas requise.
required_for	Filtre les types d’applications pour lesquels la contrainte de l’émetteur est requise lorsque required est true : all_clients (toutes les applications) ou public_clients (applications publiques uniquement). La valeur par défaut est all_clients si elle n’est pas précisée. Lorsque vous utilisez mTLS, seule la valeur all_clients est valide.

L’exemple de code suivant montre un corps de requête qui configure un serveur de ressources pour la contrainte de l’émetteur mTLS. Comme mTLS prend uniquement en charge all_clients pour required_for (qui est la valeur par défaut), il n’est pas nécessaire de le préciser :

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
  }
}'

L’exemple de code suivant montre un corps de requête qui configure un serveur de ressources pour la contrainte de l’émetteur DPoP, requise uniquement pour les applications publiques :

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"
  }
}'

L’exemple de code suivant configure la contrainte de l’émetteur DPoP comme étant requise pour toutes les applications. Comme all_clients est la valeur par défaut, required_for peut être omis :

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
  }
}'

L’exemple de code suivant désactive la contrainte de l’émetteur pour un serveur de ressources (l’équivalent de sélectionner « Never » dans l’Auth0 Dashboard) :

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 
}'