Valider les jetons dans votre API

Vérifier les access tokens Obexal sur votre resource server : validation locale par JWKS ou introspection RFC 7662, révocation, durées de vie et rotation des refresh tokens.

Votre API reçoit des access tokens émis par Obexal et doit décider, à chaque requête, si elle peut leur faire confiance. Deux approches existent : valider le JWT localement avec les clés publiques, ou interroger Obexal via l'endpoint d'introspection. Cette page couvre les deux, plus la révocation et l'hygiène des refresh tokens.

Les access tokens sont des JWT signés en RS256 (en-tête typ: at+jwt). Les refresh tokens sont des chaînes opaques : ils ne peuvent pas être validés localement, seulement introspectés ou échangés.

Validation locale avec le JWKS

Toute bibliothèque JWT standard peut valider un access token Obexal :

1. Récupérez le JWKS sur https://accounts.obexal.com/.well-known/jwks.json et mettez-le en cache (la réponse est servie avec un cache public court). Il contient la clé active et les clés retirées non expirées : la rotation est donc transparente.
2. Sélectionnez la clé par l'en-tête kid et n'acceptez que RS256 : refusez none et tout algorithme HS* (défense contre la confusion d'algorithme).
3. Vérifiez la signature, le claim iss (l'URL de votre issuer) et exp.
4. Contrôlez que l'en-tête typ du JWT vaut at+jwt : cela rejette un ID token rejoué comme access token.
5. Appliquez votre propre autorisation : scope, et aud quand c'est pertinent (les jetons délégués d'agents peuvent être liés à un resource server précis via aud).

Introspection (RFC 7662)

POST /oauth/introspect renvoie l'état vivant d'un jeton. L'endpoint est protégé : seul un client confidentiel authentifié peut l'appeler (un client public reçoit 401 invalid_client), et un client ne peut introspecter que ses propres jetons. Tout autre jeton, ainsi que tout jeton inconnu, expiré ou révoqué, répond {"active": false} sans autre détail. Les access tokens (JWT) et les refresh tokens (opaques) sont acceptés.

curl -sS -X POST https://accounts.obexal.com/oauth/introspect \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "token=$ACCESS_TOKEN"

{
  "active": true,
  "token_type": "access_token",
  "client_id": "app_a1b2c3",
  "scope": "openid profile email",
  "sub": "8f2c1e9a-4b7d-4c2e-9f1a-3d5e7b9c0a12",
  "username": "alice@example.eu",
  "iss": "https://accounts.obexal.com",
  "aud": "app_a1b2c3",
  "exp": 1751450000,
  "iat": 1751449400,
  "act": { "sub": "agent_7d4e" }
}

Le membre act n'apparaît que sur les jetons délégués : il identifie l'agent IA qui agit au nom de l'utilisateur porté par sub, chaîné en cas de délégation imbriquée. Voir Délégation par Token Exchange.

Choisir entre les deux

• La validation locale par JWKS ne coûte aucun appel réseau par requête et suit la charge de votre API. Sa limite : un jeton reste valide jusqu'à exp, la révocation n'est donc effective qu'au rythme de la durée de vie du jeton (10 minutes par défaut).
• L'introspection renvoie la vérité en temps réel : elle reflète immédiatement les révocations, y compris le kill switch d'un agent IA désactivé, dont les jetons répondent active: false avant même d'expirer. C'est aussi la seule option pour les refresh tokens. Son coût : un appel HTTP et un secret client sur votre resource server.

Un schéma courant : validation locale sur le chemin chaud, introspection pour les opérations sensibles où la révocation immédiate compte.

Durées de vie et révocation

En auto-hébergement, ces durées sont configurables ; voir Configuration.

POST /oauth/revoke (RFC 7009) révoque un refresh token. L'appel est authentifié par le client et renvoie toujours 200, même pour un jeton inconnu ou déjà révoqué (idempotent par conception) :

curl -sS -X POST https://accounts.obexal.com/oauth/revoke \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "token=$REFRESH_TOKEN" -d 'token_type_hint=refresh_token'
# 200, toujours

Les access tokens ne sont pas révocables individuellement : ils expirent, c'est pourquoi leur durée de vie est courte. Quand une invalidation instantanée est nécessaire en plus, utilisez l'introspection.

Refresh tokens : rotation et détection de rejeu

Les refresh tokens tournent à chaque usage : le jeton présenté est révoqué et un nouveau est émis dans la même chaîne, avec les mêmes scopes ou un sous-ensemble demandé. Conservez le nouveau jeton et jetez l'ancien.

Présenter un refresh token déjà révoqué est traité comme un signal de compromission, pas comme une nouvelle tentative : Obexal révoque toute la chaîne pour cet utilisateur et ce client, refuse la requête avec invalid_grant, et consigne un incident de sécurité critique (refresh_token_replay) visible dans la console d'administration.