Configurer l’authentification Private Key JWT

Décrit comment configurer de nouvelles applications et des applications existantes pour utiliser l’authentification Private Key JWT.

Private Key JWT est offert aux clients du forfait Enterprise. Pour passer à un forfait supérieur, consultez les tarifs Auth0.

L’authentification Private Key JWT prend en charge l’authentification d’application selon OIDC Connect Core Client Authentication 1.0, au moyen d’assertions JWT signées à l’aide de paires de clés asymétriques. Vous pouvez créer une nouvelle application pour utiliser private_key_jwt ou activer cette méthode d’authentification pour des applications existantes au moyen de paires de clés.

​

Prérequis

Avant de configurer une application qui s’authentifie avec Private Key JWT, vous devez générer une paire de clés RSA.

​

Configurer Private Key JWT

Auth0 Dashboard

Vous pouvez utiliser l’Auth0 Dashboard pour créer une nouvelle application et configurer les identifiants, ou pour mettre à jour une application existante.

Nous vous recommandons de stocker de façon sécuritaire le paramètre client_secret actuel avant de définir la méthode d’authentification de votre application sur Private Key JWT. Le paramètre client_secret sera masqué une fois la configuration de Private Key JWT terminée.

​

Configurer une nouvelle application pour private_key_jwt

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

2. Sélectionnez Create Application.

3. Choisissez votre type d’application.

4. Dans les paramètres de l’application, sélectionnez l’onglet Credentials.

5. Sous Authentication Methods, sélectionnez Private Key JWT.

   

6. Configurez les détails de l’identifiant :

   1. Entrez un nom pour l’identifiant.

   2. Téléversez votre certificat au format PEM ou X.509.

   3. Sélectionnez l’algorithme pour signer les assertions.

   4. Facultatif : activez l’expiration personnalisée. Sélectionnez Set an explicit expiry date for this Credential et définissez une date future.

      Vous pourriez recevoir une erreur de certificat invalide si vous soumettez un élément de clé mal formé. Pour éviter tout problème, il est préférable de téléverser directement le fichier créé par openssl.

7. Sélectionnez Add Credential.

​

Configurer une application existante

1. Accédez à Auth0 Dashboard > Applications.

2. Sélectionnez l’application que vous voulez mettre à jour.

3. Sélectionnez l’onglet Credentials.

4. Choisissez Private Key JWT.

5. Configurez les détails de l’identifiant :

   1. Entrez un nom pour l’identifiant.
   2. Téléversez votre certificat au format PEM ou X.509.
   3. Sélectionnez l’algorithme pour signer les assertions.
   4. Facultatif : activez l’expiration personnalisée. Sélectionnez Set an explicit expiry date for this Credential et définissez une date future.

6. Sélectionnez Add Credential.

​

Configurer une application pour utiliser l’authentification Secret client

1. Accédez à Auth0 Dashboard > Applications > Applications et sélectionnez l’application que vous voulez mettre à jour.
2. Sélectionnez l’onglet Credentials.
3. Choisissez Client Secret (Post) ou Client Secret (Basic).
4. Sélectionnez Save.

​

Mettre à jour l’expiration d’un identifiant

Vous pouvez mettre à jour un identifiant existant avec une date d’expiration dans l’Auth0 Dashboard.

1. Accédez à Auth0 Dashboard > Applications > Applications et sélectionnez l’application que vous voulez mettre à jour.

2. Sélectionnez l’onglet Credentials.

3. Choisissez l’identifiant que vous voulez mettre à jour et sélectionnez Edit Credential.

   

4. Sélectionnez Set an explicit expiry date for this Credential et définissez une date future.

5. Sélectionnez Update Credential.

Management API

​

Configurer une nouvelle application pour private_key_jwt

Vous pouvez créer une nouvelle application avec private_key_jwt comme méthode d’authentification à l’aide de la Management API. Effectuez un appel POST vers l’endpoint Create a Client avec le payload suivant :

curl --location --request POST 'https://{domain}/api/v2/clients' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
 "name": "{clientName}",
 "app_type": "non_interactive",
 "client_authentication_methods": {
   "private_key_jwt": {
     "credentials": [
       { 
          "name": "{credentialName}", 
          "credential_type": "public_key", 
          "pem": "{credentialPublicKey}",
          "alg": "{algorithm}",
          "expires_at": "{expiresAt}"
       }
     ]
   },
   "jwt_configuration": {
     "alg": "RS256"
   }
 }
}'

Paramètre	Description
algorithm	Algorithme utilisé pour signer les assertions. Les valeurs prises en charge sont RS256, RS384 et PS256. S’il n’est pas précisé, l’algorithme par défaut sera RS256.
clientName	Nom de votre nouvelle application.
credentialName	Nom de la clé publique.
expires_at	Facultatif. Date d’expiration de l’information d’identification au format ISO 8601. Par exemple, 2020-08-20T19:10:06.299Z. Une fois cette date passée, l’information d’identification n’est plus valide.
managementApiAccessToken	Jeton d’accès pour Management API avec le scope create:credentials.
pem	Clé publique ou certificat x.509, encodé au format PEM.
parse_expiry_from_cert	Facultatif. Un booléen indiquant qu’Auth0 doit analyser la date d’expiration lorsqu’un certificat est fourni. Si aucun certificat n’est fourni, Auth0 retournera une erreur. parse_expiry_from_cert et expires_at s’excluent également l’un l’autre. Dans ce cas, Auth0 retournera une erreur.

La clé publique au format PEM doit être échappée pour JSON avant d’être transmise à Auth0. Dans notre exemple, voici le contenu à transmettre :

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82 mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx +wIDAQAB -----END PUBLIC KEY-----

La réponse contient la propriété client_id qui liera votre application au serveur de ressources. Elle contient également un kid généré pour le credential que vous avez créé. Ce kid sera utilisé plus tard pour générer le client_assertion.

Auth0 respecte la norme JSON Web Key Thumbprint pour générer le kid de vos identifiants.

Le kid se compose d’un condensé SHA-256 de la représentation JWK de votre clé publique, encodé en base64URL.

​

Configurer une application existante

Vous pouvez également configurer une application existante pour utiliser l’authentification Private Key JWT avec l’Auth0 Management API. Vous devrez supprimer toutes les valeurs du champ token_endpoint_auth_method et ajouter des valeurs dans le champ client_authentication_methods.

Si vous mettez à jour une application de production existante afin de l’authentifier avec private_key_jwt, nous vous recommandons de conserver de manière sécurisée votre valeur client_secret actuelle pour pouvoir vous y référer ultérieurement.

Après avoir configuré private_key_jwt, vous ne pourrez plus accéder à la valeur client_secret, sauf si vous rétablissez la configuration de votre application pour utiliser un Secret client.

Créer la ressource credential

Une fois la paire de clés générée, créez la ressource d’identification. Envoyez la requête POST suivante au point de terminaison /clients de la Management API.

curl --location --request POST 'https://{domain}/api/v2/clients/{clientId}/credentials' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "name": "{credentialName}", 
          "credential_type": "public_key", 
          "pem": "{credentialPublicKey}",
          "alg": "{algorithm}",
          "expires_at ": "{expiresAt}",
}'

Paramètre	Description
algorithm	Algorithme utilisé pour signer les assertions. Les valeurs prises en charge sont RS256, RS384 et PS256. S’il n’est pas précisé, l’algorithme par défaut est RS256.
clientId	Identifiant de l’application à mettre à jour.
credentialName	Nom de la clé publique.
managementApiAccessToken	Jeton d’accès pour la Management API avec le scope create:credentials.
pem	Clé publique ou certificat X.509, au format PEM.
expires_at	Facultatif. Date d’expiration du justificatif d’authentification au format ISO 8601. Par exemple, 2020-08-20T19:10:06.299Z. Une fois cette date dépassée, le justificatif d’authentification n’est plus valide.
parse_expiry_from_cert	Facultatif. Un Boolean indiquant qu’Auth0 doit analyser la date d’expiration lorsqu’un certificat est fourni. Si aucun certificat n’est fourni, Auth0 renverra une erreur. parse_expiry_from_cert et expires_at s’excluent mutuellement. Dans ce cas, Auth0 renverra une erreur.

La clé publique PEM doit être échappée au format JSON avant d’être transmise à Auth0. Dans cet exemple, le contenu que nous devons transmettre est :

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82
mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm
Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb
jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g
Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg
IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx
+wIDAQAB
-----END PUBLIC KEY-----

Un credential ID est retourné dans la réponse. Utilisez cet ID pour l’étape suivante.

Associer le credential

Après avoir créé l’identifiant, associez-le à votre application. Votre application utilise ces identifiants lors de l’authentification avec private_key_jwt.

Effectuez une requête PATCH vers l’endpoint Update a Client de la Management API :

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "token_endpoint_auth_method": null, 
          "client_authentication_methods": {
             "private_key_jwt": {
                "credentials": [{ "id": {credentialId} }]
             }
          }
   }​​'​​

Paramètre	Description
clientId	Identifiant de l’application à mettre à jour.
managementApiAccessToken	Jeton d’accès pour Management API avec les scopes update:client et update:credentials.
credentialId	Identifiant de l’objet d’authentification que vous avez créé.
pem	La clé publique au format PEM.

Auth0 ne prend pas en charge l’utilisation de l’algorithme HS256 pour signer les JWT de l’application. Le champ jwt_configuration.alg doit être défini sur l’algorithme RS256. Pour savoir comment modifier l’algorithme de signature, consultez Modifier les algorithmes de signature de l’application.

​

Configurer une application pour utiliser l’authentification par Secret client

Pour rétablir la configuration de votre application afin d’utiliser un Secret client, vous devez désactiver client_authentication_methods et réactiver token_endpoint_auth_method avec la méthode d’authentification.

Une fois que vous aurez configuré votre méthode d’authentification sur client_secret, vos applications ne pourront plus s’authentifier à l’aide de private_key_jwt tant que vous ne les aurez pas mises à jour pour utiliser client_secret.

Exemple

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "token_endpoint_auth_method": "{tokenEndpointAuthMethod}", 
          "client_authentication_methods": null
   }​​'​​

Paramètre	Description
clientId	ID de l’application mise à jour.
managementApiAccessToken	Jeton d’accès pour la Management API avec les scopes update:client et update:credentials.
tokenEndpointAuthMethod	Méthode d’authentification retenue. Par exemple : client_secret_basic ou client_secret_post.

​

Mettre à jour les identifiants avec un champ d’expiration

Vous pouvez mettre à jour un identifiant existant avec une date d’expiration à l’aide de l’endpoint Update a credential de la Management API.

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId}/credentials/{credentialId} ' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "expires_at": {expiresAt}
   }'

Paramètre	Description
managementApiAccessToken	Jetons d’accès pour la Management API avec le scope update:credentials.
clientId	L’application que vous souhaitez mettre à jour.
expires_at	La date d’expiration des informations d’identification au format ISO 8601. Par exemple, 2020-08-20T19:10:06.299Z.

Le seul champ que vous pouvez mettre à jour est le champ expires_at. Les autres attributs sont immuables et nécessitent une rotation du credential pour être modifiés.

​

Limites des identifiants

Auth0 impose une taille minimale de 2048 bits pour les clés RSA et une taille maximale de 4096 bits. Les applications peuvent avoir au plus deux identifiants configurés.

​

Effectuer une rotation des identifiants

Pour éviter les fuites de clés, Auth0 recommande d’effectuer périodiquement une rotation des identifiants. Pour savoir comment faire, consultez Effectuer une rotation des identifiants.

​

En savoir plus

• Identifiants d’application
• Paramètres des identifiants
• S’authentifier au moyen de Private Key JWT