Tokens y JWKS: verificar los JWT de Didit Authentication

• https://<name>.auth.didit.me para una aplicación de producción,
• https://<name>.sandbox.auth.didit.me para una aplicación de sandbox,
• o tu propio dominio personalizado, una vez que esté activo.

​

Descubrimiento y claves

• Tipo de respuesta code y modo de respuesta query.
• Tipos de concesión authorization_code y refresh_token.
• Solo el método PKCE S256. Los clientes son públicos: no hay secreto de cliente y client_id es el ID de tu aplicación.
• Algoritmo de firma ES256 (claves P-256).
• Scopes openid, email, phone, profile y offline_access.

​

Caché y rotación

• Cada clave tiene un kid; los nuevos ID de clave empiezan por k_. Cada token indica su clave en el encabezado kid.
• Las claves rotan cada 30 días. Didit publica la siguiente clave un día antes de que empiece a firmar y mantiene publicada la clave anterior durante un día después de que deje de hacerlo. Por eso, un JWKS en caché durante 5 minutos sigue verificando a lo largo de una rotación.
• Guarda las claves en caché por kid. Cuando un token indique un kid que no tienes, vuelve a obtener el JWKS, como máximo una vez por minuto, y rechaza el token si la clave sigue sin aparecer.
• Cuando Didit revoca una clave comprometida, la elimina del JWKS de inmediato, y GET /session/ rechaza todos los tokens firmados con esa clave. Una clave de reemplazo empieza a firmar inmediatamente, sin el día de publicación anticipada. Un JWKS guardado en caché hasta 5 minutos antes sigue aceptando la clave revocada y todavía no conoce la de reemplazo, por lo que los tokens nuevos pueden fallar la verificación sin conexión hasta que la caché se actualice.

​

Iniciar sesión

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

​

Intercambiar el código

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"
}

​

Claims del token de acceso

​

Verificar un token en tu servidor

1. alg es ES256 y typ es at+jwt. Rechaza cualquier otro algoritmo, incluido none.
2. El kid está en el JWKS de tu aplicación y la firma se verifica.
3. iss es igual al emisor que configuraste y aud es igual al ID de tu aplicación.
4. exp e iat son válidos, con un margen de hasta 60 segundos de diferencia de reloj, y sub, sid y jti están presentes.
5. act es null. El token de acceso de un agente de IA se firma con la misma clave y lleva los mismos typ, iss y aud; solo act lo distingue. Recházalo, salvo que el endpoint acepte agentes: en ese caso, permite solo lo que conceda act.scopes. GET /session/ siempre rechaza el token de un agente.

// 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

​

Comprobar la sesión

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

​

Tokens de actualización

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

• El token de actualización es una cadena aleatoria, válida hasta que termina la sesión.
• Reutilizarlo termina la sesión. Cuando vuelve a llegar un token de actualización ya usado, Didit lo trata como una señal de robo: revoca la sesión y devuelve 400 {"error": "invalid_grant"}. Los tokens de la sesión también dejan de funcionar, incluidos los de la actualización anterior: el token de actualización deja de funcionar y el token de acceso deja de funcionar de inmediato al invocar GET /session/, aunque sigue verificándose offline hasta que expira, en un plazo de 5 minutos.
• Ejecuta una sola actualización a la vez por sesión, en todas las pestañas, dispositivos e instancias de servidor, y sustituye los tres tokens a la vez.
• Si una actualización falla con 400 o no obtienes respuesta, vuelve a iniciar sesión. No la reintentes a ciegas: reintentar una actualización que sí se completó es una reutilización.
• Un 503 {"error": "temporarily_unavailable"} significa que la actualización no se realizó y que tu token de actualización sigue funcionando. Vuelve a intentarlo con backoff.
• Didit responde con un 429 antes de ejecutar la actualización, así que reintenta después de Retry-After. El endpoint de tokens admite 30 solicitudes por minuto y 300 por hora por dirección IP. Además, todas las solicitudes POST y DELETE de tu aplicación comparten los contadores de protección contra bots: 60 solicitudes por minuto por dirección IP entre esos endpoints, 30 por minuto por dispositivo y 1,000 por minuto para toda la aplicación, incluidos los navegadores y los pasos de inicio de sesión.
• Con tokens de acceso de 5 minutos, 300 actualizaciones por hora cubren a unas 25 personas que se mantienen activas. Si tu servidor actualiza tokens para muchas personas desde una misma dirección, actualiza solo cuando una solicitud necesite un token nuevo y, cuando puedas, hazlo en el navegador o en la app.

​

Cerrar sesión

• supera session_lifetime (30 días por defecto) o idle_timeout (1 día por defecto),
• la persona vuelve a iniciar sesión cuando no se permiten varias sesiones,
• la persona restablece su contraseña mientras revoke_on_password_change está activado,
• tu equipo la revoca o bloquea a la persona en la consola,
• se vuelve a enviar un token de actualización ya usado.

​

Duración

​

Guarda las credenciales según su propósito

• Guarda las claves de API de verificación y los tokens de la consola en tu servidor.
• Guarda los tokens de acceso del navegador en memoria siempre que sea posible. En aplicaciones renderizadas en el servidor, usa cookies seguras HttpOnly y protege contra CSRF las solicitudes autenticadas con cookies.
• Guarda los tokens de actualización en aplicaciones móviles en el almacenamiento protegido por la plataforma. Borra el estado local después de cerrar sesión.
• Nunca pongas tokens en las URL ni en los logs.