Autenticação API: OAuth2, JWT, HMAC

TL; DR

OAUTH2/OIDC + JWT é um padrão para aplicações de clientes e integrações de servidor com autorizações complexas (scopes/roles/tenants), SSO e TTL de tokens curtos.
Assinaturas HMAC são as melhores opções para webhooks e simples chamadas parceiras «server→server», com verificação determinada e proteção rígida contra replay.
Reforce a segurança: mTLS ou DPoP (sender-constrained tokens), TTL (5-15 min), rotação de chaves (JWKS), refresh-tokens com rotação/anti-reuse, validação rigorosa 'aud/iss/exp/nbf/kid' e policy-as-código gateway.

1) Mapa de soluções: o que aplicar

2) OAuth2/OIDC: fluxos e clientes

2. 1 Fluxo

Código Autorization + PKCE (Web/Mobile): protege o código de autorização contra interceptação.
Cliente Credentals: server↔server sem usuário; scopes - o mínimo necessário.
Data Device: para dispositivos sem navegador.
Refresh Tóquio: somente para clientes de confiança; roteie e inclua o reuse detation.

2. 2 Tipos de cliente

Confidential (servidores, BFF): guardam segredos; use o mTLS.
Público (SPA/mobile): o segredo não pode ser armazenado → PKCE, DPoP, TTL curtos e scopes limitados.

3) JWT: estrutura, prazo, verificação

3. 1 Campos (clims)

Obrigatórios: «iss», «sub», «aud», «exp», «iat», «nbf», «jti», «scope »/« percussões», «tenant», «kid».

3. 2 Prazo de vida

Access tocen: 5-15 minutos.
Refresh tocen: dias/semanas, rotativo a cada troca; Se voltarmos a usar o antigo, bloqueamos a sessão.
Clock skew: tolerância ≤ 60 segundos.

3. 3 JWKS e chaves

Armazenamento de chaves no KMS/Vault, 'kid' é obrigatório.
Duas chaves ativas (rolling), transbordamento a cada 60 ou 90 dias ou no incidente.
Cash JWKS em gateway ≤ 5 minutos, com deficiência automática.

3. 4 Verificação em gateway/serviços

Contrate: assinatura, «aud» (serviços permitidos), «iss», «exp/nbf», lista de bloqueios (revocation).
Não confira os campos do corpo sem a verificação da assinatura; ignore 'alg = none'.

Authorization: Bearer <JWT>
X-Trace-Id: <uuid>

4) Vinculação do tocador ao cliente: mTLS, DPoP

mTLS (TLS certificados de cliente): O token só é emitido e validado se houver um certificado de cliente → o token é inútil fora do vínculo chave + certificado.
DPoP (Demonstration of Proof-Postation): O cliente assina cada pedido com uma chave descartável → proteção contra replay e roubo de token em clientes públicos.
Para rotas críticas (mutações de pagamento) - exigir um dos mecanismos.

5) Autorização: scopes, roles, ABAC

Scopes - ação mínima ('payments: write', 'payouts: status: read').
Roles - unidades para almirantes; não use-os diretamente sem scopes.
ABAC - atributos no tocante ('tenant', 'country', 'kyc _ level', 'risk _ flags') → políticas no gateway/OPA.
Política ao nível da rota/campo (GraphQL) e da operação de domínio (REST/gRPC).

6) assinaturas HMAC: webhooks e parceiros

6. 1 Conceito

Cada integração tem um segredo.

Legenda acima da linha canônica: «timestamp + »\n« + method + »\n «+ path + »\n« + sha256 (body) »

X-Signature: v1=base64(hmac_sha256(secret, canonical_string))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF...

Janela do tempo: ≤ 300 segundos; pedidos de «X-Timestamp» vencidos/futuros para recusar.
Idempotidade: Guarde 'X-Event-Id' em TTL (24 h) - Retire a duplicação.

6. 2 Melhores práticas

Segredos em KMS/Vault, rotação a cada 90 dias.
Para clientes públicos HMAC não é adequado (o segredo é escoado); use o OAuth2/DPoP.

7) Proteção contra replay, brute force e vazamentos

Nonce/' jti 'para operações sensíveis; Lista negra de identificadores usados.
Rate/cotas: por chave/cliente/tenante/rota; operações «caras» são quotas individuais.
IP/ASN/Geo allow-lists para parceiros e webhooks.
Conteúdo-tipo allow ('aplicação/json'), limite de tamanho corporal.
Camuflar o PII nos logs; a proibição de logar tokens/segredos.

8) Erros e respostas (formato único)

json
{
"error": "invalid_token",
"error_description": "expired",
"trace_id": "4e3f-..."
}

• '401' - Não/token nevalida (WWW-Autenticate).
• '403' - direitos insuficientes (scope/ABAC).
• '429' - limites/quotas.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) Políticas de prazos e sessões

Access ≤ 15 min; Refresh - rotação + reuse detation (apresentaram o antigo - uma revisão da sessão).
Webhooks HMAC: assinaturas TTL ≤ 5 min; nova entrega com backoff exponencial.
Revogar a sessão/chave → entrar imediatamente em uma lista de revocação (em dinheiro para gateway ≤ 1 min).

10) Observação e auditoria

Correlação por 'trace _ id '/' span _ id'.
Métricas: auth sucess rate, '401/403/429', latência OIDC/JWKS, taxa de rotação, reuse refresh, proporção de tráfego DPoP/mTLS.
«Quem, quando, com que 'sub/tenant/scope' causou o quê», alterações de chaves/segredos, assinaturas HMAC reprovadas.

11) Incorporação à API Gateway

Validação JWT (JWKS kesh) e OPA/ABAC na entrada.
perfis para clientes/parceiros confiáveis.
Verificação HMAC de webhooks em edge (antes de serviços internos).
Rate/Cota pólis, circuito-breaker para o provedor OIDC (armazenar JWK).
Função-flags: desativação rápida do cliente/chave, alteração do algoritmo de assinatura.

12) Mini-snippets

Pseudo: verificação do JWT

pseudo jwks = cache. getOrFetch(iss + "/.well-known/jwks. json")
key = jwks[kid]
assert verify_signature(jwt, key)
assert aud in ALLOWED_AUDIENCES and iss in TRUSTED_ISSUERS assert now in [nbf-60s, exp+60s]

Pseudo: verificar HMAC webhook

pseudo canonical = timestamp + "\n" + method + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
assert abs(now - timestamp) <= 300 assert not seen(event_id)
assert timingSafeEqual(sig, header["X-Signature"].split("v1=")[1])
markSeen(event_id, ttl=86400)

Exemplo de Políticas Scope (OPA/Rego ideia)

rego allow {
input. jwt. scope[_] == "payments:write"
input. jwt. tenant == input. route. tenant
}

13) Playbooks incidentes

Fuga de chave privada/assinante JWT: reversão de chaves, atualização do JWKS, desativação imediata do antigo ('kid' → deny), deficiência de refresh, logout forçado.
Substituição de webhooks: rotação de segredos, IP allow-list, reforço da janela 'X-Timestamp', reaproveitamento de eventos omitidos.
Replay/Brutfort: incluir DPoP/mTLS em rotas críticas, estreitar quotas, blocos temporários por IP/ASN, incluir 'jti' - bloqueador.
Outage OIDC: degradação de tokens em dinheiro (grace), circuito-breaker do provedor, notificação dos clientes.

14) Folhas de cheque de implementação

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL: Access ≤ 15 min, Refresh com rotação e reuse detation
• JWKS: duas chaves ativas, 'kid', dinheiro ≤ 5 min
• Webhooks: HMAC v1, 'X-Timestamp', 'X-Event-Id', janela ≤ 300 segundos, Idempotação
• Sender-constrained: mTLS/DPoP em rotas críticas
• ABAC/OPA: scopes + tenant/risk em políticas de gateway
• Rate/Quota и 429; IP/ASN allow-lists para parceiros
• Auditoria e alertas de (401/403/429, reuse refresh, assinaturas HMAC)

• Não logar tokens/segredos/mapas completos de corpo
• Camuflagem PII; Suporte DSAR; o tempo de armazenamento dos logs é limitado

15) Anti-pattern

'alg = none' ou credibilidade de token sem comprovação de assinatura/JWKS.
Acesso de longa duração (relógio/dia).
Um segredo HMAC comum em todos os parceiros.
Webhooks sem timstamp/idempotação.
Refresh-tokens sem rotação e sem reuse detation.
Falta de 'aud '/' iss' - validação e' kid '- rotação.
Armazenamento de segredos em variáveis de ambiente sem KMS/Vault.

16) NFL/SLO (referências)

OIDC/JWKS disponibilidade ≥ 99. 95% (edge-dinheiro reduz a dependência).
JWT validação suplemento em gateway ≤ 2-5 ms p95.
Erros de autenticação ('401') ≤ 0. 5% do tráfego total (sem contar os bots).
Webhooks assinados: proporção de ≥ 99 credenciadas com sucesso. 9%, média de atraso na entrega ≤ 3 s.

Currículo

Combine os mecanismos OAuth2/OIDC + JWT para usuários e ricos cenários de servidor, HMAC para webhooks/parceiros simples, e para operações críticas para mTLS/DPoP. Mantenha os TTL curtos, as chaves de rotação (JWKS), as políticas ABAC/OPA rigorosas, proteja os contornos contra replay e vazamentos, e automatize tudo ao nível da API Gateway. Assim, a autenticação será previsível, escalável e segura - sem compromissos para a UX e monetização.