Configurer l’authentification Private Key JWT

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

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

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

​

Prérequis

Avant de configurer une application qui s’authentifie au moyen de 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 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. Saisissez un nom pour l’identifiant.

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

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

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

      Vous pourriez recevoir une erreur de certificat invalide si vous soumettez une clé mal formée. 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 souhaitez mettre à jour.

3. Sélectionnez l’onglet Credentials.

4. Choisissez Private Key JWT.

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

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

6. Sélectionnez Add Credential.

​

Configurer une application pour utiliser l’authentification Client Secret

1. Accédez à Auth0 Dashboard > Applications > Applications et sélectionnez l’application que vous souhaitez 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 la date d’expiration d’un identifiant existant dans l’Auth0 Dashboard.

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

2. Sélectionnez l’onglet Credentials.

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

   

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

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 une requête 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 indiqué, l’algorithme par défaut est RS256.
clientName	Nom de votre nouveau client.
credentialName	Nom de la clé publique.
expires_at	Facultatif. Date d’expiration du justificatif au format ISO 8601. Par exemple, 2020-08-20T19:10:06.299Z. Une fois cette date passée, le justificatif n’est plus valide.
managementApiAccessToken	Jeton d’accès pour la Management API ayant la portée create:credentials.
pem	Clé publique ou certificat x.509, encodé au format PEM.
parse_expiry_from_cert	Facultatif. Booléen indiquant si 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 également mutuellement. Dans ce cas, Auth0 renverra une erreur.

La clé publique PEM doit être échappée en 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 associera votre application au serveur de ressources. Elle contient également un kid généré pour le justificatif que vous avez créé, qui sera utilisé plus tard pour générer le client_assertion.

Auth0 suit la norme JSON Web Key Thumbprint pour générer le kid de vos informations d’authentification.

Le kid correspond à un condensé SHA256 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 pour qu’elle s’authentifie avec private_key_jwt, nous vous recommandons de conserver en lieu sûr votre valeur actuelle de client_secret pour référence ultérieure.

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

Créer la ressource d’identification

Une fois la paire de clés générée, créez la ressource d’identification. Effectuez la requête POST suivante à l’endpoint /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. Si rien n’est précisé, l’algorithme par défaut est RS256.
clientId	ID de l’application à mettre à jour.
credentialName	Nom de la clé publique.
managementApiAccessToken	Jeton d’accès pour l’API de gestion doté de la portée create:credentials.
pem	Clé publique ou certificat x.509, encodés au format PEM.
expires_at	Facultatif. Date d’expiration de l’information d’authentification au format ISO 8601. Par exemple : 2020-08-20T19:10:06.299Z. Une fois cette date passée, l’information d’authentification n’est plus valide.
parse_expiry_from_cert	Facultatif. Un booléen qui indique qu’Auth0 doit extraire 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 ID de justificatif est renvoyé dans la réponse. Utilisez cet ID pour l’étape suivante.

Associer l’identifiant

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

Envoyez une requête PATCH à 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	ID de l’application à mettre à jour.
managementApiAccessToken	Jeton d’accès pour l’API de gestion avec les portées update:client et update:credentials.
credentialId	ID des informations d’identification que vous avez créées.
pem	La clé publique au format PEM.

Auth0 ne prend pas en charge l’utilisation de HS256 comme algorithme de signature JWT pour 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 Client Secret, vous devez désactiver client_authentication_methods et réactiver token_endpoint_auth_method avec la méthode d’authentification.

Une fois votre méthode d’authentification configurée avec client_secret, vos applications ne pourront plus s’authentifier au moyen de private_key_jwt tant que vous ne les aurez pas mises à jour pour s’authentifier avec 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 finale. Par exemple : client_secret_basic ou client_secret_post.

​

Correctif pour les informations d’identification avec un champ d’expiration

Vous pouvez mettre à jour des informations d’identification existantes 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 les autorisations update:credentials.
clientId	Le client à mettre à jour.
expires_at	La date d’expiration de l’identifiant d’authentification 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 2 048 bits et une taille maximale de 4 096 bits pour les clés RSA. Les applications peuvent avoir au plus deux identifiants configurés.

​

Effectuer la rotation des identifiants

Pour éviter qu’une fuite de clés ne compromette la sécurité, Auth0 recommande d’effectuer périodiquement la rotation de la paire de clés. Pour savoir comment procéder, consultez Effectuer la rotation des identifiants.

​

En savoir plus

• Identifiants de l’application
• Paramètres des identifiants
• S’authentifier à l’aide de Private Key JWT