Token Introspection: valide tokens opacos

Token Introspection no Node.js permite que uma API consulte o Authorization Server para descobrir se um token está ativo e quais atributos, escopos, cliente e usuário estão associados a ele. O mecanismo é especialmente útil com access tokens opacos, que não carregam claims verificáveis localmente.

A introspecção melhora revogação quase imediata, mas adiciona uma dependência de rede em cada validação ou em parte delas. Por isso, precisa de autenticação do resource server, timeout curto, cache controlado e política de falha segura.

Endpoint de introspecção

O endpoint é configurado pelo provedor. A API envia o token por POST:

const body = new URLSearchParams({
  token,
  token_type_hint: 'access_token'
});

const response = await fetch(introspectionEndpoint, {
  method: 'POST',
  headers: {
    authorization: `Basic ${basicCredentials}`,
    'content-type': 'application/x-www-form-urlencoded'
  },
  body,
  signal: AbortSignal.timeout(1000)
});

A autenticação do resource server pode usar client secret, private_key_jwt ou mTLS. Prefira métodos que não enviem secret compartilhado quando suportados.

Resposta ativa

{
  "active": true,
  "scope": "catalog.read orders.write",
  "client_id": "web-app",
  "username": "user-10",
  "token_type": "Bearer",
  "exp": 1793072400,
  "sub": "user-10",
  "aud": "catalog-api",
  "iss": "https://identity.example"
}

O único campo obrigatório é active. Trate os demais conforme o contrato do provedor.

Token inativo

{ "active": false }

Não revele ao cliente se o token expirou, foi revogado ou nunca existiu. Retorne autenticação inválida de forma genérica.

Validando a resposta

Mesmo vindo do Authorization Server, valide tipos e contexto:

• active === true;
• audience inclui sua API;
• issuer é o esperado;
• expiração ainda é válida;
• client ID permitido;
• escopos necessários;
• tenant coerente.

Escopos

const scopes = new Set(String(data.scope ?? '').split(' ').filter(Boolean));

if (!scopes.has('catalog.read')) {
  throw forbidden();
}

Escopo autoriza uma capacidade geral. A aplicação ainda deve verificar acesso ao recurso específico.

Autenticação do endpoint

Não use credenciais de um cliente frontend para introspecção. Registre a API como resource server ou cliente confidencial com permissões mínimas.

mTLS

O endpoint pode exigir certificado de cliente. Configure CA, certificado e chave protegidos. Consulte mTLS no Node.js.

private_key_jwt

A API assina uma assertion curta com sua chave privada. O provedor valida a assinatura. Use aud igual ao token endpoint ou endpoint definido e um jti único.

Cache positivo

Introspectar cada requisição pode elevar latência. Cacheie resultados ativos por poucos segundos, nunca além de exp:

const ttlSeconds = Math.min(
  30,
  Math.max(0, data.exp - Math.floor(Date.now() / 1000))
);

Um cache maior reduz capacidade de revogação imediata.

Cache negativo

Tokens inválidos podem ser repetidos em ataques. Cache negativo por poucos segundos reduz carga, mas use hash do token como chave, nunca o token em texto puro.

const key = createHash('sha256').update(token).digest('hex');

Proteção de memória

Limite quantidade de entradas. Um atacante pode enviar tokens aleatórios para encher o cache. Use LRU, tamanho máximo e rate limiting.

Falha do Authorization Server

Para APIs protegidas, normalmente falhe fechado: se não é possível validar, não aceite. Retorne 503 ou erro de autenticação conforme a política, evitando tratar indisponibilidade como token inválido permanente.

Circuit breaker

Durante falha prolongada, um circuit breaker reduz chamadas. Tokens com resultado ativo ainda dentro de cache podem continuar por uma janela explicitamente aprovada. Não estenda arbitrariamente além da expiração.

Timeout budget

A introspecção consome o deadline da requisição. Use timeout curto e propague cancelamento. Leia Timeout Budget no Node.js.

Tokens opacos versus JWT

JWT pode ser validado localmente com JWKS, reduzindo dependência de rede. Token opaco simplifica revogação e esconde claims do cliente. O modelo ideal depende de latência, escala e requisitos de revogação.

Introspecção de JWT

Alguns sistemas introspectam JWT mesmo podendo validá-lo localmente, para verificar revogação ou estado atual. Isso combina assinatura local e consulta seletiva em operações sensíveis.

Token binding

Quando o token é vinculado a certificado ou chave, valide os campos de confirmação, como cnf. Um token roubado não deve funcionar sem a chave correspondente.

Middleware

async function authenticate(req, res, next) {
  try {
    const token = readBearerToken(req);
    const auth = await introspectCached(token);

    req.auth = Object.freeze({
      subject: auth.sub,
      clientId: auth.client_id,
      scopes: parseScopes(auth.scope)
    });

    next();
  } catch (error) {
    res.status(401).json({ error: 'invalid_token' });
  }
}

Não anexe a resposta inteira sem filtrar claims.

Rate limiting

Limite requisições inválidas por IP, cliente e rota. O endpoint de introspecção também deve aplicar limites ao resource server.

Observabilidade

Monitore:

• cache hit e miss;
• latência;
• respostas ativas e inativas;
• timeouts e indisponibilidade;
• falhas de autenticação do resource server;
• audience e escopo rejeitados;
• circuit breaker;
• idade do cache.

Nunca registre o token. Use hash truncado apenas para correlação controlada.

Testes

• token ativo;
• inativo;
• expirado;
• audience incorreta;
• escopo ausente;
• endpoint lento;
• cache positivo e negativo;
• revogação durante cache;
• credencial da API inválida;
• resposta malformada;
• mTLS.

Erros comuns

• introspecção sem timeout;
• cache além da expiração;
• não validar audience;
• registrar token;
• usar credencial de frontend;
• falhar aberto;
• cache ilimitado de tokens aleatórios;
• confundir escopo com autorização do recurso;
• tratar indisponibilidade como token revogado.

Conclusão

Token Introspection no Node.js permite validar tokens opacos e observar revogação com baixa demora. O custo é uma dependência online do Authorization Server.

Use autenticação forte da API, timeout curto, cache limitado e validação de audience e escopos. Preserve falha fechada e proteja o serviço de identidade com rate limiting e circuit breaker.

Consulte a RFC 7662 sobre OAuth Token Introspection e a RFC 8705 sobre OAuth mTLS.