S’authentifier avec Private Key JWT

Décrit comment créer une assertion pour utiliser l’authentification Private Key JWT.

Avant de commencer

Vous devez créer une nouvelle application dans Auth0 Dashboard ou convertir une application existante avant de continuer. Pour en savoir plus, consultez Configurer l’authentification Private Key JWT.

Vous devez suivre deux étapes pour vous authentifier avec private_key_jwt:

1. Créez l’assertion du client. Cette assertion est un JWT signé à l’aide de la clé privée générée avec la paire de clés. Pour savoir comment générer une paire de clés, consultez Configurer l’authentification Private Key JWT.
2. Utilisez l’assertion pour vous authentifier auprès d’Auth0.

​

Créer l’assertion

Vous pouvez utiliser l’un des SDKs d’Auth0 pour créer automatiquement une assertion. Si vous n’utilisez pas nos SDKs, vous devrez construire l’assertion vous-même.

L’assertion est un JSON Web Token (JWT) qui doit contenir les propriétés et claims suivants :

Tous les claims sont obligatoires, sauf indication contraire. Pour en savoir plus sur les claims JWT, consultez JSON Web Token Claims.

• En-tête

  • alg : l’algorithme utilisé pour signer l’assertion. Il doit correspondre à celui indiqué lorsque vous avez créé le credential de votre application.
  • kid: (facultatif) le kid généré par Auth0 pour le credential. Le kid est créé au moment de la création du credential.

• Payload

  • iss: le Client ID de votre application. Vous trouverez cette valeur dans les paramètres de votre application, sous Auth0 Dashboard > Applications > Applications, puis dans l’onglet Settings.

  • sub: le Client ID de votre application. Vous trouverez également cette valeur dans les paramètres de votre application, sous Auth0 Dashboard > Applications > Applications, puis dans l’onglet Settings.

  • aud: l’URL du tenant Auth0 ou du domaine personnalisé qui reçoit l’assertion. Par exemple : https://{yourTenant}.auth0.com/. Incluez la barre oblique finale.

    Si vous avez configuré un domaine personnalisé pour votre tenant Auth0, vous pouvez l’utiliser comme claim aud. Dans ce cas, nous vous recommandons d’utiliser le domaine personnalisé.

  • iat (facultatif), nbf (facultatif) et exp : les claims Issued At, Not Before et Expiration, définis avec les horodatages appropriés. Un décalage d’horloge maximal de 10 secondes est permis pour iat et nbf (s’ils sont présents) afin d’assurer l’interopérabilité. L’assertion du client est un jeton à usage unique, et nous recommandons la durée d’expiration la plus courte possible. Auth0 prend en charge une durée de vie maximale de 5 minutes pour un jeton.

  • jti : un ID de claim unique créé par le client. Nous recommandons d’utiliser le format Universally Unique Identifier (UUID).

    Ce JWT est un jeton à usage unique et doit être traité comme tel en lui donnant une courte durée d’expiration. Nous recommandons un maximum de 1 minute.

Le jeton doit ensuite être signé avec la clé privée que vous avez générée lorsque vous avez créé ou configuré votre application pour authentification Private Key JWT. Pour savoir comment faire, consultez la spécification JSON Web Token.

Nous vous recommandons de construire le jeton à l’aide d’outils standard ou de bibliothèques tierces qui prennent en charge cette fonctionnalité d’emblée, plutôt que de l’implémenter vous-même à partir de zéro. Pour en savoir plus sur les bibliothèques compatibles, consultez la liste sur JWT.io.

​

Exemple

Dans l’exemple ci-dessous, le script Node.js utilise le package jose pour générer l’assertion :

const { SignJWT } = require('jose')
const crypto = require("crypto");
const uuid = require("uuid");

async function main() {
 const privateKeyPEM = crypto.createPrivateKey(/**
   Lisez le contenu de votre clé privée ici. Nous vous recommandons de stocker votre clé privée
   dans une infrastructure sécurisée. 
 */);

 const jwt = await new SignJWT({})
   .setProtectedHeader({ 
      alg: 'RS256', // ou RS384 ou PS256
      kid: '(OPTIONAL) KID_GENERATED_BY_AUTH0' 
   })
   .setIssuedAt()
   .setIssuer('CLIENT_ID')
   .setSubject('CLIENT_ID')
   .setAudience('https://YOUR_TENANT.auth0.com/') // ou votre CUSTOM_DOMAIN
   .setExpirationTime('1m')
   .setJti(uuid.v4())
   .sign(privateKeyPEM);
  console.log(jwt)
}

main();

Exemple d’assertion du client signée avec une clé privée :

Ce qui correspond à :

{
  "alg": "RS256",
  "kid": "my kid"
}
{
  "iat": 1626684584,
  "iss": "my client id",
  "sub": "my client id",
  "aud": "https://mytenant.auth0.com/",
  "exp": 1626684644,
  "jti": "e4dc8ed1-b108-4901-8bbc-c07a791817e7"
}

Après avoir généré le JWT avec les informations requises, vous pouvez maintenant authentifier votre application auprès d’Auth0.

​

Échanger une assertion contre des jetons d’accès

L’exemple suivant utilise le Client Credential Flow. L’authentification Private Key JWT peut aussi être utilisée avec d’autres types d’octroi qui permettent de remplacer client_secret par client_assertion.

Pour échanger l’assertion JWT contre un jeton d’accès, envoyez une requête au point de terminaison de jeton de l’Authentication API avec les paramètres suivants :

• $client_assertion : assertion JWT
• $resource_server_identifier : identifiant du serveur de ressources. Pour en savoir plus, consultez Enregistrer des API.

curl --location --request POST 'https://$tenant/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=$client_assertion' \
  --data-urlencode 'audience=$resource_server_idenifier'

​

Points de terminaison pris en charge

En plus du point de terminaison https://$tenant/oauth/token, les points de terminaison suivants de l’API d’authentification Auth0 prennent en charge l’authentification private_key_jwt pour les applications configurées :

• POST /oauth/revoke
• POST /mfa/challenge
• POST /passwordless/start

​

Limites de l’assertion

La longueur maximale de l’assertion JWT est de 2 048 octets.

Les claims contenus dans l’assertion sont soumis aux limites suivantes :

• iss : 64 caractères
• sub : 64 caractères
• jti : 64 caractères
• alg : 16 caractères

​

Pour en savoir plus

• Configurer l’authentification Private Key JWT
• Authentification client Private Key JWT pour les connexions Okta et OIDC