Jetons et JWKS : vérifier les JWT d'authentification

• https://<name>.auth.didit.me pour une application de production,
• https://<name>.sandbox.auth.didit.me pour une application sandbox,
• ou votre propre domaine personnalisé, une fois qu’il est actif.

​

Découverte et clés

• Le type de réponse code et le mode de réponse query.
• Les types d’octroi authorization_code et refresh_token.
• La méthode PKCE S256 uniquement. Les clients sont publics : il n’existe pas de secret client, et client_id correspond à l’identifiant de votre application.
• L’algorithme de signature ES256 (clés P-256).
• Les scopes openid, email, phone, profile et offline_access.

​

Cache et rotation

• Chaque clé possède un kid ; les nouveaux identifiants de clé commencent par k_. Chaque token indique sa clé dans l’en-tête kid.
• Les clés tournent tous les 30 jours. Didit publie la clé suivante un jour avant qu’elle ne commence à signer, et maintient la clé précédente publiée pendant un jour après qu’elle a cessé de signer. Un JWKS mis en cache pendant 5 minutes permet donc de continuer à vérifier les tokens pendant une rotation.
• Mettez les clés en cache par kid. Lorsqu’un token mentionne un kid que vous ne possédez pas, récupérez à nouveau le JWKS, au maximum une fois par minute, et rejetez le token si la clé est toujours absente.
• Lorsque Didit révoque une clé compromise, elle retire immédiatement la clé du JWKS, et GET /session/ rejette chaque token signé par cette clé. Une clé de remplacement commence à signer immédiatement, sans le jour de publication anticipée. Un JWKS mis en cache jusqu’à 5 minutes plus tôt accepte encore la clé révoquée et ne connaît pas encore le remplacement ; les nouveaux tokens peuvent donc échouer à la vérification hors ligne jusqu’au rafraîchissement du cache.

​

Démarrer la connexion

{issuer}/sign-in?redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256

​

Échanger le code

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/token/" \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "CODE_FROM_CALLBACK",
    "code_verifier": "YOUR_PKCE_VERIFIER",
    "redirect_uri": "https://app.example.com/auth/callback"
  }'

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "id_token": "eyJhbGciOiJFUzI1NiIs...",
  "refresh_token": "N4yZTl6y24YKYq77X_SO...",
  "token_type": "Bearer",
  "expires_in": 299,
  "session_id": "c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1"
}

​

Revendications du jeton d’accès

​

Vérifier un jeton sur votre serveur

1. alg vaut ES256 et typ vaut at+jwt. Rejetez tout autre algorithme, y compris none.
2. Le kid figure dans le JWKS de votre application et la signature est valide.
3. iss est égal à votre émetteur configuré, et aud est égal à l’ID de votre application.
4. exp et iat sont valides, avec une tolérance d’écart d’horloge de 60 secondes au maximum, et sub, sid et jti sont présents.
5. act vaut null. Le jeton d’accès d’un agent IA est signé avec la même clé et porte les mêmes typ, iss et aud ; seul act permet de le distinguer. Rejetez-le, sauf si l’endpoint accepte les agents : dans ce cas, n’autorisez que ce que act.scopes accorde. GET /session/ rejette toujours le jeton d’un agent.

// npm install jose
import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = process.env.DIDIT_AUTH_ISSUER; // https://<name>.auth.didit.me
const AUDIENCE = process.env.DIDIT_APPLICATION_ID;
// Cache keys for 5 minutes; refetch an unknown kid at most once a minute.
const jwks = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`), {
  cacheMaxAge: 5 * 60 * 1000,
  cooldownDuration: 60 * 1000,
});

export async function verifyAccessToken(token) {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
    audience: AUDIENCE,
    algorithms: ["ES256"],
    typ: "at+jwt",
    clockTolerance: 60,
    maxTokenAge: "5m", // also rejects an iat in the future
    requiredClaims: ["sub", "sid", "jti", "exp", "iat"],
  });
  if (payload.act !== null) throw new Error("agent tokens are not accepted");
  return payload; // payload.vendor_data is the person across Didit products
}

# pip install "pyjwt[crypto]"
import os
import threading
import time

import jwt

ISSUER = os.environ["DIDIT_AUTH_ISSUER"]  # https://<name>.auth.didit.me
AUDIENCE = os.environ["DIDIT_APPLICATION_ID"]
jwks = jwt.PyJWKClient(f"{ISSUER}/.well-known/jwks.json", lifespan=300)
refresh_lock = threading.Lock()
last_refresh = 0.0


def signing_key(kid: str | None) -> jwt.PyJWK:
    # PyJWKClient refetches for every unknown kid: limit it to once a minute.
    global last_refresh
    keys = {key.key_id: key for key in jwks.get_signing_keys()}
    if kid not in keys:
        with refresh_lock:
            if time.monotonic() - last_refresh >= 60:
                last_refresh = time.monotonic()
                fresh = jwks.get_signing_keys(refresh=True)
                keys = {key.key_id: key for key in fresh}
    if kid not in keys:
        raise jwt.InvalidTokenError("unknown signing key")
    return keys[kid]


def verify_access_token(token: str) -> dict:
    header = jwt.get_unverified_header(token)
    if header.get("typ") != "at+jwt":
        raise jwt.InvalidTokenError("not an access token")
    claims = jwt.decode(
        token,
        signing_key(header.get("kid")).key,
        algorithms=["ES256"],
        audience=AUDIENCE,
        issuer=ISSUER,
        leeway=60,
        options={"require": ["iss", "aud", "sub", "sid", "jti", "exp", "iat"]},
    )
    if "act" not in claims or claims["act"] is not None:
        raise jwt.InvalidTokenError("agent tokens are not accepted")
    return claims

​

Vérifier la session

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/session/" \
  -H "Authorization: Bearer $DIDIT_ACCESS_TOKEN"

​

Rafraîchir les jetons

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/token/" \
  -H 'Content-Type: application/json' \
  -d '{"grant_type": "refresh_token", "refresh_token": "YOUR_REFRESH_TOKEN"}'

• Le jeton de rafraîchissement est une chaîne aléatoire, valable jusqu’à la fin de la session.
• La réutilisation met fin à la session. Lorsqu’un jeton de rafraîchissement déjà utilisé est à nouveau reçu, Didit y voit le signe d’un vol : il révoque la session et renvoie 400 {"error": "invalid_grant"}. Les jetons de la session cessent aussi de fonctionner, y compris ceux du rafraîchissement précédent : leur jeton de rafraîchissement échoue, et leur jeton d’accès échoue immédiatement sur GET /session/, bien qu’il reste valable hors ligne jusqu’à son expiration, dans un délai de 5 minutes.
• Ne lancez qu’un seul rafraîchissement à la fois pour une session, entre onglets, appareils et instances de serveur, et remplacez les trois jetons ensemble.
• Si un rafraîchissement échoue avec 400 ou n’obtient aucune réponse, relancez la connexion. Ne réessayez pas aveuglément : une nouvelle tentative après un rafraîchissement réussi constitue une réutilisation.
• Un 503 {"error": "temporarily_unavailable"} signifie que le rafraîchissement n’a pas eu lieu et que votre jeton de rafraîchissement fonctionne toujours. Réessayez avec un délai progressif.
• Didit répond par un 429 avant l’exécution du rafraîchissement : réessayez après Retry-After. L’endpoint de jetons autorise 30 requêtes par minute et 300 par heure et par adresse IP. En plus, chaque POST et DELETE de votre application partage des compartiments de protection contre les bots : 60 requêtes par minute et par adresse IP pour l’ensemble de ces endpoints, et 30 par minute et par appareil. Pour l’ensemble de l’application, les rafraîchissements disposent d’un compartiment de 6 000 par minute, et chaque autre POST et DELETE (navigateurs et étapes de connexion compris) d’un compartiment de 3 000 par minute, afin que les rafraîchissements n’épuisent jamais votre quota de connexions.
• Avec des jetons d’accès de 5 minutes, 300 rafraîchissements par heure suffisent pour environ 25 personnes restant actives. Si votre serveur rafraîchit les jetons de nombreuses personnes depuis une même adresse, ne rafraîchissez que lorsqu’une requête a besoin d’un nouveau jeton, et rafraîchissez dans le navigateur ou l’application lorsque c’est possible.

​

Déconnexion

• elle dépasse session_lifetime (30 jours par défaut) ou idle_timeout (1 jour par défaut),
• la personne se reconnecte alors que les sessions multiples sont désactivées,
• la personne réinitialise son mot de passe alors que revoke_on_password_change est activé,
• votre équipe la révoque ou bloque la personne dans la console,
• un token de renouvellement déjà utilisé est envoyé à nouveau.

​

Durées de vie

​

Stocker les identifiants selon leur usage

• Conservez les clés API de vérification et les tokens de la console sur votre serveur.
• Conservez les tokens d’accès du navigateur en mémoire lorsque c’est possible. Pour les applications rendues côté serveur, utilisez des cookies sécurisés HttpOnly et protégez les requêtes authentifiées par cookie contre les attaques CSRF.
• Stockez les tokens de renouvellement mobiles dans un stockage protégé par la plateforme. Effacez l’état local après la déconnexion.
• Ne placez jamais de tokens dans des URL ou dans des journaux.