Tokens e JWKS: verificar JWT de autenticação Didit

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

​

Descoberta e chaves

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

​

Cache e rotação

• Cada chave tem um kid; os novos IDs de chave começam por k_. Cada token indica a sua chave no cabeçalho kid.
• As chaves rodam a cada 30 dias. A Didit publica a chave seguinte um dia antes de começar a assinar, e mantém a chave anterior publicada durante um dia depois de deixar de assinar. Um JWKS mantido em cache durante 5 minutos permite, por isso, continuar a verificar assinaturas durante uma rotação.
• Coloque as chaves em cache por kid. Quando um token indicar um kid que não tem, vá buscar de novo o JWKS, no máximo uma vez por minuto, e rejeite o token se a chave continuar em falta.
• Quando a Didit revoga uma chave comprometida, remove-a imediatamente do JWKS, e GET /session/ rejeita todos os tokens assinados por essa chave. Uma chave de substituição começa a assinar de imediato, sem o dia de publicação antecipada. Um JWKS em cache até 5 minutos antes continua a aceitar a chave revogada e ainda não conhece a substituta, pelo que os novos tokens podem falhar a verificação offline até a cache ser atualizada.

​

Iniciar sessão

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

​

Afirmações do token de acesso

​

Verifique um token no seu servidor

1. alg é ES256 e typ é at+jwt. Rejeite qualquer outro algoritmo, incluindo none.
2. O kid está no JWKS da sua aplicação, e a assinatura é validada.
3. iss é igual ao emissor configurado, e aud é igual ao ID da sua aplicação.
4. exp e iat são válidos, admitindo 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 tem o mesmo typ, iss e aud; só act o distingue. Rejeite-o, a não ser que o endpoint aceite agentes: nesse caso, permita apenas o que act.scopes concede. GET /session/ rejeita sempre 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

​

Verifique a sessão

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

​

Tokens de atualizaçã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 atualização é uma cadeia aleatória, válida até a sessão terminar.
• A reutilização termina a sessão. Quando um token de atualização já usado volta a chegar, a Didit interpreta-o como sinal de roubo: revoga a sessão e devolve 400 {"error": "invalid_grant"}. Os tokens da sessão também deixam de funcionar, incluindo os da atualização anterior: o respetivo token de atualização falha e o seu token de acesso falha de imediato em GET /session/, embora continue a ser validado offline até expirar, no máximo em 5 minutos.
• Execute uma só atualização de cada vez para uma sessão, em todos os separadores, dispositivos e instâncias do servidor, e substitua os três tokens em conjunto.
• Se uma atualização falhar com 400 ou não obtiver resposta, volte a iniciar sessão. Não tente de novo às cegas: uma nova tentativa depois de uma atualização bem-sucedida constitui uma reutilização.
• Um 503 {"error": "temporarily_unavailable"} significa que a atualização não aconteceu e que o seu token de atualização continua a funcionar. Tente novamente com espera progressiva.
• A Didit responde com um 429 antes de a atualização ser executada, por isso tente novamente após Retry-After. O endpoint de tokens permite 30 pedidos por minuto e 300 por hora por endereço IP. Além disso, cada POST e DELETE da sua aplicação partilha baldes de proteção contra bots: 60 pedidos por minuto por endereço IP nesses endpoints e 30 por minuto por dispositivo. Para a aplicação inteira, as atualizações têm um balde de 6.000 por minuto, e cada outro POST e DELETE (incluindo os de navegadores e passos de início de sessão) tem um de 3.000 por minuto, pelo que as atualizações nunca consomem os seus pedidos de início de sessão.
• Com tokens de acesso de 5 minutos, 300 atualizações por hora cobrem cerca de 25 pessoas que permanecem ativas. Se o seu servidor atualizar os tokens de muitas pessoas a partir do mesmo endereço, atualize apenas quando um pedido precisar de um novo token, e faça a atualização no navegador ou na aplicação sempre que for possível.

​

Terminar sessão

• ultrapassa session_lifetime (predefinido: 30 dias) ou idle_timeout (predefinido: 1 dia),
• a pessoa inicia sessão novamente quando as sessões múltiplas estão desativadas,
• a pessoa redefine a palavra-passe com revoke_on_password_change ativo,
• a sua equipa revoga a sessão ou bloqueia a pessoa na consola,
• um token de atualização já utilizado é enviado novamente.

​

Durações

​

Guardar credenciais consoante a finalidade

• Guarde as chaves de API de verificação e os tokens da consola no seu servidor.
• Guarde os tokens de acesso do navegador em memória sempre que possível. Em aplicações renderizadas no servidor, use cookies seguros HttpOnly e proteja os pedidos autenticados por cookies contra CSRF.
• Guarde os tokens de atualização de dispositivos móveis em armazenamento protegido pela plataforma. Limpe o estado local após terminar a sessão.
• Nunca coloque tokens em URLs ou registos.