Aller au contenu principal

Jeton opaque (Opaque token)

Lors du processus d'authentification, si aucune ressource n'est spécifiée, Logto émettra un jeton d’accès opaque (opaque access token) au lieu d’un JWT. Le jeton opaque est une chaîne aléatoire et il est beaucoup plus court qu’un JWT :

{
  "access_token": "some-random-string", // jeton opaque
  "expires_in": 3600,
  "id_token": "eyJhbGc...aBc", // JWT
  "scope": "openid profile email",
  "token_type": "Bearer"
}

Le jeton opaque peut être utilisé pour appeler le point de terminaison userinfo et pour accéder aux ressources protégées nécessitant une authentification. Puisqu’il ne s’agit pas d’un JWT, comment le serveur de ressources peut-il le valider ?

Logto fournit un point de terminaison d’introspection qui peut être utilisé pour valider les jetons opaques. Par défaut, le point de terminaison d’introspection est /oidc/token/introspection et accepte les requêtes POST. Le paramètre suivant est requis :

  • token : le jeton opaque à valider

Le point de terminaison nécessite également une authentification du client. Vous pouvez utiliser l’une des méthodes suivantes :

  • Authentification HTTP Basic : Utilisez l’en-tête Authorization avec la valeur Basic <base64-encoded-credentials>. Les identifiants doivent être l’ID client et le secret client séparés par un deux-points (:) et encodés en base64.
  • Authentification HTTP POST : Utilisez les paramètres client_id et client_secret :
    • client_id : l’ID client de l’application ayant demandé le jeton
    • client_secret : le secret client de l’application ayant demandé le jeton

L’ID client (ID de l’application) et le secret client (secret de l’application) peuvent être les identifiants d’une application "web traditionnelle" ou "machine à machine" dans Logto. Le point de terminaison d’introspection retournera une erreur si les identifiants sont invalides.

Le point de terminaison d’introspection retourne un objet JSON avec les revendications (claims) du jeton :

{
  "active": true, // si le jeton est valide ou non
  "sub": "1234567890", // le sujet du jeton (l’ID utilisateur)
  "acr": "urn:logto:acr:1fa", // niveau d’assurance d’authentification, si atteint
  "amr": ["pwd"], // méthodes d’authentification utilisées lors de l’interaction
  "auth_time": 1787745600 // moment où l’utilisateur s’est authentifié (en secondes epoch)
}

Si le jeton est invalide, le champ active sera à false et les autres revendications seront omises. Voir Authentification step-up pour savoir comment valider acr, amr et auth_time. Notez que les jetons d’accès JWT structurés ne peuvent pas être introspectés via /oidc/token/introspection — il faut toujours valider les jetons d’accès JWT localement avec le JWKS de votre tenant.

Voici un exemple non normatif de requête d’introspection :

curl --location \
  --request POST 'https://[tenant-id].logto.app/oidc/token/introspection' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=some-random-string' \
  --data-urlencode 'client_id=1234567890' \
  --data-urlencode 'client_secret=1234567890'

N’oubliez pas de remplacer [tenant-id] par l’ID de votre tenant.

Jeton opaque et organisations​

Les jetons opaques peuvent être utilisés pour récupérer les informations d’appartenance à une organisation via le point de terminaison userinfo. Lorsque vous demandez la portée urn:logto:scope:organizations, le point de terminaison userinfo retournera les revendications liées à l’organisation de l’utilisateur, telles que organizations (IDs d’organisation) et organization_data.

Cependant, les jetons opaques ne peuvent pas être utilisés comme jetons d’organisation. Les jetons d’organisation sont toujours émis au format JWT car :

  1. Les jetons d’organisation contiennent des revendications spécifiques à l’organisation (comme organization_id et les permissions associées) qui doivent être validées par les serveurs de ressources.
  2. Le format JWT permet aux serveurs de ressources de vérifier le jeton et d’extraire le contexte organisationnel sans appels API supplémentaires.

Pour obtenir un jeton d’organisation, vous devez utiliser le flux de jeton de rafraîchissement ou le flux client credentials avec les paramètres d’organisation.