Tokens
Sur cette page
TOSIAM supporte deux modèles de tokens OAuth2 : stateful (stockés en CTS) et stateless (JWT autonomes). Le choix impacte la scalabilité, la révocation et la latence de validation.
Tokens stateful (CTS)#
Par défaut, les access tokens sont des références opaques stockées dans le Core Token Store (CTS). La validation d’un token stateful nécessite une requête au CTS.
Avantages : révocation immédiate, pas de risque de fuite de données dans le token.
Inconvénients : chaque validation = requête LDAP, le CTS est un point central.
Tokens stateless (JWT)#
Les tokens JWT sont auto-porteurs : un serveur de ressources peut les valider en vérifiant leur signature avec le JWKS, sans appeler TOSIAM.
TOSIAM enregistre tout de même dans le CTS les métadonnées de chaque jeton stateless émis, et tient une liste de révocation : un jeton révoqué est refusé par TOSIAM (introspection, userinfo), mais pas par un serveur de ressources qui ne fait que vérifier la signature.
Avantages : validation locale, adapté aux microservices distribués, meilleure scalabilité.
Inconvénients : un serveur de ressources qui valide localement ne voit pas les révocations (le jeton reste accepté jusqu’à son expiration), taille plus grande.
Anatomie d’un access token JWT TOSIAM#
L’émetteur (iss) est l’URL OAuth2 du royaume : https://<serveur>/tosiam/oauth2 pour le royaume racine, https://<serveur>/tosiam/oauth2/<royaume> pour un sous-royaume. L’audience (aud) est le client_id du client qui a obtenu le jeton.
{
"sub": "alice",
"iss": "https://tosiam.example.com/tosiam/oauth2",
"aud": ["mon-client"],
"exp": 1735689600,
"iat": 1735686000,
"jti": "a1b2c3d4-e5f6-...",
"scope": "openid email profile api:read",
"client_id": "mon-client",
"realm": "/",
"cnf": {
"x5t#S256": "cert-thumbprint"
}
}Clés de signature (JWKS)#
GET /oauth2/{realm}/connect/jwk_uriLes clients doivent récupérer le JWKS dynamiquement (ou le mettre en cache et le recharger quand une signature ne se vérifie pas), pour suivre un changement de clé.
Tokens Macaroon#
TOSIAM supporte les tokens Macaroon : tokens porteurs avec caveats ajoutables sans interaction serveur. Un Macaroon peut être restreint (caveat first-party) par n’importe qui possédant le token.
# Inspecter un Macaroon
POST /oauth2/{realm}/macaroon/inspect
token=MACAROON_TOKEN
# Restreindre un Macaroon (ajouter un caveat)
POST /oauth2/{realm}/macaroon/restrict
token=MACAROON_TOKEN&caveat=time < 2024-12-31Tokens Refresh#
Le refresh token est émis avec l’access token pour les grant types qui le supportent (authorization_code, password, CIBA). Sa durée de vie est configurable indépendamment.
| Propriété | Stateful | Stateless JWT |
|---|---|---|
| Stockage | CTS (LDAP) | Jeton autonome, métadonnées dans le CTS |
| Révocation | Immédiate | Liste de révocation côté TOSIAM ; invisible d’une validation locale |
| Validation | Appel CTS | Vérif. signature locale |
| Taille | Référence opaque (~40 chars) | JWT signé (~500–1000 chars) |
| Scalabilité | Limitée par le CTS | Horizontale |
Usage unique des codes et des refresh tokens#
Un code d’autorisation ne s’échange qu’une fois, et un refresh token qui tourne (réglage « Émettre un refresh token au rafraîchissement ») ne sert qu’une fois. Plusieurs requêtes qui présentent le même jeton au même moment, même sur des serveurs TOSIAM différents, ne peuvent pas obtenir toutes des jetons : une seule réserve le jeton, les autres reçoivent invalid_grant. Le rejeu d’un code révoque en plus les jetons émis avec lui (RFC 6749, section 4.1.2).
Depuis la version 3.38.0, un jeton stocké dans le CTS est réservé par une modification conditionnelle de son entrée :
- l’échange d’un code le marque « émis » ;
- la rotation d’un refresh token le marque « utilisé ».
La modification porte un contrôle d’assertion LDAP (RFC 4528) : l’annuaire ne l’applique que si le jeton n’est pas déjà marqué, de façon atomique. La réservation et le marquage tiennent ainsi en une seule écriture, qui existait déjà.
Une entrée séparée du CTS, un marqueur, réserve le jeton dans deux cas :
| Cas | Raison |
|---|---|
| Refresh token stateless (JWT) | Pas d’entrée du CTS à modifier |
| Annuaire du CTS sans contrôle d’assertion | La modification conditionnelle est refusée ; TOSIAM ajoute alors un marqueur |
Jusqu’à la version 3.37, chaque réservation ajoutait un marqueur, supprimé à son expiration. Sur un tir de charge, ces marqueurs représentaient environ 12 % des écritures du CTS, et autant de rejeux entre ses serveurs.
Comme le marqueur, la réservation suppose que toutes les écritures d’un même jeton vont au même serveur du CTS (affinité sur l’identifiant du jeton).
Réutilisation d’un refresh token remplacé#
Depuis la version 3.38.0, quand un refresh token déjà remplacé est présenté de nouveau par son client, TOSIAM révoque les jetons de la même autorisation (RFC 9700, section 4.14.2) : le refresh token actif et les access tokens.
Si un refresh token volé sert à la fois au voleur et au client légitime, l’un des deux présente tôt ou tard un jeton déjà remplacé. TOSIAM ne peut pas savoir lequel : il coupe donc l’autorisation, ce qui écarte le voleur. Le client légitime doit demander une nouvelle autorisation.
La réponse est invalid_grant dans tous les cas, que l’autorisation soit révoquée ou non.
| Réglage du fournisseur OAuth2 | Valeur par défaut | Effet |
|---|---|---|
Révoquer l’autorisation à la réutilisation d’un jeton de rafraîchissement remplacé (refreshTokenReuseDetectionEnabled) | activé | Désactivé, le jeton est seulement refusé |
Tolérance à la réutilisation d’un jeton de rafraîchissement (refreshTokenReuseGracePeriod) | 10 secondes | Délai après le remplacement pendant lequel le jeton est refusé sans révoquer l’autorisation ; 0 révoque dès la première réutilisation |
Conservation d’un jeton de rafraîchissement remplacé (refreshTokenReplacedRetention) | 1 jour (86 400 secondes) | Durée maximale pendant laquelle un jeton remplacé reste dans le CTS, de 1 seconde à 1 an ; après elle, il est purgé |
La tolérance protège un client qui rejoue une requête dont il a perdu la réponse, par exemple après une coupure réseau. Ce client n’obtient pas de nouveau jeton, mais son autorisation reste en place.
Conservation d’un jeton remplacé#
Depuis la version 3.38.0, un refresh token remplacé ne reste plus dans le CTS jusqu’à sa propre expiration. Lors du remplacement, son expiration est ramenée à la fin de la durée de conservation. Sa réutilisation est refusée par invalid_grant avant comme après cette date, mais l’autorisation n’est révoquée que pendant la conservation : ensuite, le jeton est refusé comme un jeton inconnu.
Le réglage arbitre donc entre la taille du CTS et la détection tardive :
- un client qui rafraîchit toutes les heures, avec des refresh tokens de 7 jours, laisse au plus 168 jetons dans le CTS sans limite de conservation, et 25 avec une conservation de 1 jour ;
- si un voleur rafraîchit le premier et que le client légitime ne revient qu’après la fin de la conservation, le vol n’est pas détecté : le client doit s’authentifier de nouveau et le voleur garde son jeton jusqu’à son expiration.
Une conservation égale ou supérieure à la durée de vie des refresh tokens redonne le comportement d’avant. Elle convient aux clients qui peuvent rester absents plusieurs jours, comme une application mobile. Les jetons déjà remplacés lors de la mise à jour gardent leur expiration.
Les refresh tokens stateless ne sont pas concernés : leur réservation dure toute leur vie, sans quoi un jeton purgé redeviendrait valide. Il en va de même avec un annuaire qui ne prend pas en charge le contrôle d’assertion.
Rien n’est révoqué dans les cas suivants :
- le jeton est présenté par un autre client ;
- le jeton est inconnu, ou sa signature n’est pas celle du fournisseur ;
- le jeton a expiré.
Chaque révocation est écrite dans le journal du serveur et dans l’événement d’audit d’accès de la requête : le détail porte oauth2_event (refresh_token_reuse), revoked_grant (l’identifiant de l’autorisation) et client_id. Le compteur am_oauth2_token_revoked_total augmente d’une unité.
Limites :
- Un client public ne s’authentifie pas : quiconque détient l’un de ses anciens refresh tokens peut faire révoquer son autorisation. C’est le coût accepté par la RFC 9700 ; pour un client public, l’attaque ne donne pas d’accès.
- Avec des tokens stateless, la révocation passe par la liste de révocation : si
blacklistingEnabledest désactivé dans le service OAuth2 global, le refresh token actif et les access tokens restent valables. - Un refresh token en cours de remplacement au moment précis de la révocation peut y échapper.
Jetons ops (gestion de session OpenID Connect)#
Quand un jeton d’identité est émis pour un utilisateur qui a une session TOSIAM, il porte la revendication org.forgerock.openidconnect.ops. Cette valeur opaque, dérivée de l’identifiant de la session sans le révéler, permet au point end_session de retrouver la session à partir du jeton d’identité que lui présente l’application.
Depuis la version 3.38.0 :
- la revendication est la même pour toutes les applications d’une session ;
- une session avec état la garde dans sa propre entrée du CTS, où
end_sessionla retrouve par une recherche indexée. Aucune entrée n’est ajoutée au CTS pour elle : elle disparaît avec la session ; - une session sans état n’a pas d’entrée dans le CTS : la revendication désigne un jeton ops, une entrée du CTS qui fait le lien avec la session (voir ci-dessous) ;
- un jeton d’identité sans session, celui d’un rafraîchissement par exemple, n’a pas de revendication
ops.
Jusqu’à la version 3.37, chaque session ouverte sur une application OpenID Connect avait son jeton ops, ajouté au CTS puis supprimé à la fin de la session. Sur un tir de charge, ces jetons représentaient environ 15 % des écritures du CTS, et autant de rejeux entre ses serveurs. Après une montée de version, les jetons ops déjà émis restent lus par end_session et disparaissent à l’expiration de leur jeton d’identité.
Sessions sans état#
Une session sans état (stateless) n’a pas d’entrée dans le CTS, mais son jeton ops en est une. Depuis la version 3.38.0 :
- une session n’a qu’un jeton ops, commun à toutes ses applications et réutilisé d’un jeton d’identité à l’autre. Il vit au moins aussi longtemps que le jeton d’identité le plus durable émis pour la session ;
- il est supprimé à la déconnexion de la session et à sa suppression. Une session sans état qui expire n’est vue par personne : son jeton ops reste alors jusqu’à l’expiration du jeton d’identité ;
- il contient l’identifiant de la session, c’est-à-dire la session elle-même : l’entrée est plus volumineuse que pour une session avec état ;
- il tient aussi la liste des applications à avertir par la déconnexion par canal dérobé, qu’une session sans état ne peut pas garder elle-même.
end_session et la déconnexion ne mettent fin à une session sans état côté serveur que si la liste noire des sessions sans état est activée (service de session, réglage global, désactivé par défaut, lu au démarrage). Sans elle, le jeton ops est supprimé et les applications sont averties, mais la session reste acceptée jusqu’à son expiration.
Jusqu’à la version 3.37, une demande d’autorisation OpenID Connect présentée avec une session sans état échouait (login_required).
Sur une session déjà terminée, end_session répond sans erreur : il n’y a plus rien à terminer.
Désactiver les jetons ops#
Le réglage Conserver les jetons ops (storeOpsTokens) du fournisseur OAuth2 est activé par défaut :
Realm → Services → OAuth2 Provider
→ Conserver les jetons ops : activéDésactivé, les jetons d’identité n’ont plus de revendication ops, et TOSIAM ne crée plus de jeton ops pour les sessions sans état :
| Parcours | Réglage désactivé |
|---|---|
end_session avec id_token_hint | répond sans erreur, et redirige vers post_logout_redirect_uri s’il est fourni, mais ne termine pas la session |
Déconnexion par l’API des sessions (/json/sessions?_action=logout) ou par l’interface | inchangée |
| Déconnexion back-channel, session avec état | inchangée : la session tient elle-même la liste de ses applications |
| Déconnexion back-channel, session sans état | les applications ne sont plus averties |
Depuis la version 3.38.0, le réglage n’économise plus d’écriture dans le CTS pour les sessions avec état : leur revendication ne coûte qu’une clé d’index dans leur propre entrée. Il n’y a donc plus de raison de le désactiver pour alléger le CTS, sauf pour des sessions sans état dont aucune application n’utilise end_session ni la déconnexion back-channel.
Pas d’iframe de session#
TOSIAM ne fournit pas OpenID Connect Session Management : la découverte ne publie pas check_session_iframe et les réponses d’autorisation ne portent pas session_state. Ce mécanisme repose sur un cookie lu depuis une iframe tierce, que les navigateurs bloquent. Pour qu’une application apprenne la fin d’une session, utiliser la déconnexion back-channel.
Jusqu’à la version 3.37, la découverte publiait une adresse /connect/checkSession qui ne fonctionnait pas ; elle est retirée en 3.38.0.
Configuration des tokens stateless#
Dans la configuration du service OAuth2 du realm :
Realm → Services → OAuth2 Provider
→ Use Stateless Access & Refresh Tokens : Enabled
→ Signing Algorithm : RS256 (ou ES256)
→ Token Signing Key Alias : (alias de la clé dans le keystore)Le jeton d’accès stateless est signé par le fournisseur, jamais par le client, selon la même règle que les jetons d’accès au format JWT :
| Algorithme du fournisseur | Signature du jeton d’accès | Signature du refresh token |
|---|---|---|
| RS256, RS512, ES256… | algorithme du fournisseur | algorithme du fournisseur |
| HS256 (défaut), HS384, HS512 | RS256, clé publiée dans le JWKS | algorithme du fournisseur, secret partagé |
Un serveur de ressources vérifie donc toujours le jeton d’accès avec le JWKS, sans détenir de secret. Le réglage idTokenSignedResponseAlg du client ne concerne que ses id_token, et le chiffrement des id_token ne s’applique pas au jeton d’accès.
Depuis la version 3.38.0 : ces jetons étaient auparavant signés comme les
id_tokendu client. Un serveur de ressources qui vérifie le jeton avec le secret du client doit passer au JWKS.
Avec statelessTokenEncryptionEnabled, le refresh token est signé de la même façon, puis chiffré avec la clé de TOSIAM. Il reste opaque pour le client, et il se révoque comme un refresh token non chiffré.
Mis à jour le