Tokens e JWKS: verifique JWTs da Didit Authentication

• https://<name>.auth.didit.me para uma aplicação em produção,
• https://<name>.sandbox.auth.didit.me para uma aplicação de sandbox,
• ou seu próprio domínio personalizado, depois de ativado.

​

Descoberta e chaves

• Tipo de resposta code e modo de resposta query.
• Tipos de concessão authorization_code e refresh_token.
• Apenas o método PKCE S256. Os clientes são públicos: não há segredo de cliente, e client_id é o ID da sua aplicação.
• Algoritmo de assinatura ES256 (chaves P-256).
• Escopos openid, email, phone, profile e offline_access.

​

Cache e rotação

• Cada chave tem um kid; os novos IDs de chave começam com k_. Todo token indica sua chave no cabeçalho kid.
• As chaves são rotacionadas a cada 30 dias. A Didit publica a próxima chave um dia antes de ela começar a assinar e mantém a chave anterior publicada por um dia depois que ela deixa de assinar. Assim, um JWKS em cache por 5 minutos continua verificando durante uma rotação.
• Armazene as chaves em cache por kid. Quando um token indicar um kid que você não tem, busque o JWKS novamente, no máximo uma vez por minuto, e rejeite o token se a chave continuar ausente.
• Quando a Didit revoga uma chave comprometida, ela remove a chave do JWKS imediatamente, e GET /session/ rejeita todos os tokens assinados por essa chave. Uma chave substituta começa a assinar na hora, sem o dia de publicação antecipada. Um JWKS em cache há até 5 minutos ainda aceita a chave revogada e ainda não conhece a substituta, então os novos tokens podem falhar na verificação offline até o cache ser atualizado.

​

Iniciar o login

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

​

Trocar o 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 do token de acesso

​

Verificar um token no seu servidor

1. alg é ES256 e typ é at+jwt. Rejeite qualquer outro algoritmo, inclusive none.
2. O kid está no JWKS da sua aplicação, e a assinatura é válida.
3. iss é igual ao emissor configurado, e aud é igual ao ID da sua aplicação.
4. exp e iat são válidos, com tolerância de até 60 segundos de diferença de relógio, e sub, sid e jti estão presentes.
5. act é null. O token de acesso de um agente de IA é assinado com a mesma chave e traz os mesmos typ, iss e aud; só act o diferencia. Rejeite-o, a menos que o endpoint aceite agentes: nesse caso, permita apenas o que act.scopes concede. GET /session/ sempre rejeita o token de um 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

​

Verificar a sessão

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

​

Tokens de renovação

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

• O token de renovação é uma string aleatória, válida até o fim da sessão.
• A reutilização encerra a sessão. Quando um token de renovação já usado chega novamente, a Didit trata isso como sinal de roubo: ela revoga a sessão e retorna 400 {"error": "invalid_grant"}. Os tokens da sessão também deixam de funcionar, inclusive os da renovação anterior: o token de renovação deles falha, e as requisições GET /session/ com esses tokens de acesso falham imediatamente, embora ainda seja validado offline até expirar, em até 5 minutos.
• Execute uma renovação por vez para cada sessão, considerando abas, dispositivos e instâncias de servidor, e substitua os três tokens juntos.
• Se uma renovação falhar com 400 ou não houver resposta, inicie o login novamente. Não tente novamente às cegas: uma nova tentativa após uma renovação que de fato deu certo é uma reutilização.
• Um 503 {"error": "temporarily_unavailable"} significa que a renovação não aconteceu e que seu token de renovação continua funcionando. Tente novamente com backoff.
• A Didit responde com 429 antes de executar a renovação, então tente novamente depois de Retry-After. O endpoint de token permite 30 requisições por minuto e 300 por hora por endereço IP. Além disso, todos os POST e DELETE da sua aplicação compartilham buckets de proteção contra bots: 60 requisições por minuto por endereço IP somando esses endpoints, 30 por minuto por dispositivo e 1.000 por minuto para a aplicação inteira, incluindo navegadores e etapas de login.
• Com tokens de acesso de 5 minutos, 300 renovações por hora atendem cerca de 25 pessoas que permanecem ativas. Se o seu servidor faz renovações para muitas pessoas a partir de um único endereço, renove apenas quando uma requisição precisar de um novo token e, sempre que possível, faça a renovação no navegador ou no app.

​

Sair da sessão

• ela ultrapassa session_lifetime (padrão de 30 dias) ou idle_timeout (padrão de 1 dia),
• a pessoa entra novamente enquanto múltiplas sessões estão desativadas,
• a pessoa redefine a senha enquanto revoke_on_password_change está ativado,
• sua equipe a revoga ou bloqueia a pessoa no console,
• um refresh token já usado é enviado novamente.

​

Tempos de vida

​

Armazene credenciais de acordo com a finalidade

• Mantenha as chaves de API de verificação e os tokens do console no seu servidor.
• Mantenha os access tokens do navegador em memória sempre que possível. Para aplicações renderizadas no servidor, use cookies HttpOnly seguros e proteja as requisições autenticadas por cookie contra CSRF.
• Armazene os refresh tokens de dispositivos móveis no armazenamento protegido da plataforma. Limpe o estado local depois de sair da sessão.
• Nunca coloque tokens em URLs ou logs.