Segurança API e tokens

Resumo curto

A segurança da API é um conjunto de mecanismos de autenticação, autorização, proteção criptográfica, anti-abuso e observabilidade que garante que a solicitação atende o sujeito esperado para o recurso esperado no contexto esperado. O artefato-chave é o token (ou a assinatura do pedido) que prova o direito de chamada. Boa arquitetura baseia-se em tokens curtos, escopos claros, privilégios mínimos, proteção contra repetições, rate limiting e procedimentos operacionais (rotações, auditorias, incidentes).

Modelos de autenticação API: quando e o que escolher

Chave API (segredo estático)

Simples para integrações B2B e cenários de baixo risco. Não apresenta contexto, requer armazenamento do lado de fora do serviço.
Use apenas IP/ASN allow-list, quotas fixas, TTL curto e rotações.

OAuth 2. 1 / OIDC

O padrão para as integrações personalizadas e parceiras é access tocen (breve) + refresh tocen (rotação) + escopos.
Clientes públicos - com PKCE; clientes confidential - com segredo de cliente/mTLS.

Client Credentials (m2m)

Mashina→mashina: access token para serviços de escopo e audiência bem definidos, muitas vezes sem refresh (recall).

mTLS (TLS mútuo)

Liga a identidade ao canal. Ideal para integrações de alto risco ou de pagamento (PoP acima do TLS).
Pode ser combinado com o OAuth (os tokens são apenas para clientes mTLS).

Assinaturas de solicitação (HMAC/EdDSA)

Quando você precisa de um PoP independente de transporte: título da assinatura, timestamp e nonte. Confortável para webhooks e verificação off-line.

Formatos e tipos de token

JWT (JWS assinados)

Autossuficientes, verificadas localmente; «iss», «sub», «aud», «exp», «iat», «jti», «scope» são obrigatórios.
Risco - A crítica é mais complexa: use TTL (5-15 min) e lista de «jti» retirados nos incidentes.

JWE (JWT criptografado)

É necessário se o payload é sensível (PII). O custo é maior que a complexidade e os custos gerais.

Reference tokens

Identificadores opacos são verificados através da introspecção no Offshore Server - mais fácil de rever/centralizar.

PoP/DPoP

Associar o tocador à chave do cliente ou à sessão TLS reduz o valor do token roubado.

Conteúdo do token: mínimo suficiente

• 'iss' (issuer), 'sub' (subject), 'aud' (sistema/recurso alvo), 'exp' (prazo), 'iat', 'nbf' (opcional), 'jti'.
• 'scope '/' percussions' (mínimo necessário), 'tenant' (para multi-genéricos), 'device _ compliant '/' amr' (método de autenticação), 'ip '/' asn' (se aplicável a uma política).

• TTL para access (5-15 min), refresh - 12-48 h (rotativo).
• O público ('aud') é um recurso estritamente específico, senão o token é «reutilizável».
• Escopos - ação e objeto (por exemplo, 'payments: withdraw. read`).
• Tamanho: ≤ 2-4 KB para cabeçalhos e proxy; caso contrário, pode haver problemas com os Gatwees.

Autorizações e políticas

RBAC + ABAC: rol + contexto (organização, geo, risco, estado do dispositivo).
PEP/PDP: Verificar o token e tomar uma decisão na entrada API/proxy (Envoy/OPA) antes do aplicativo.
As regras declaratórias são: armazenar no Git, fazer policy-tests no CI.

rego package policy. withdraw

default allow = false

allow {
input. token. aud == "wallet-api"
input. token. scope[_] == "payments:withdraw. create"
input. device. compliant == true input. risk. score < 70
}

Assinatura de consulta (HMAC) e anti-replay

Webhooks, integração sem OAuth, duplo teste de operações críticas.

X-Client-Id: <id>
X-Timestamp: 2025-11-05T13:20:10Z
X-Nonce: 4d1f...a2
X-Signature: base64(HMAC_SHA256(secret, method + "\n" + path + "\n" + sha256(body) + "\n" + timestamp + "\n" + nonce))

• Rejeitar pedidos com o relógio do tempo> £300 s.
• Nonte armazenar 5-15 min e não aceitar repetições (replay-dinheiro).
• Assinar a representação canonizada do pedido (método, caminho, query, hash corporal).

Idempotidade e proteção transacional

Idempotency-Key para operações de débito/pagamento/criação: chave idêntica → o mesmo efeito.
O tempo de vida da chave é ≥ tempo de trabalho (normalmente 24-72 h).
A lógica do lado do servidor é comparar as configurações de solicitação com as configuradas anteriormente para esta chave.

Clientes de navegador e celular

PKCE obrigatório (clientes públicos).
Refresh-token no navegador - evitar; se necessário - ROTATION + resposta à repetição (detecção replay).
Armazenamento: fases de armazenamento> armazenamento local; melhor: Os tokens são responsáveis por backend for frontend (BFF).
SameSite, Secure, HttpOnly для cookie; CORS - aparentes allow-lists, cabeçalhos e métodos; preflight-cajar com segurança.

m2m e integrações de alto risco

mTLS + OAuth2 Clientes Credentals com escopos e 'aud'.
IP/ASN allow-list no gateway.
PoP/DPoP ou assinaturas HMAC acima do TLS para operações críticas.
Quotas e rate limits para organização/cliente/chave.

Rotações, retiradas e resposta a incidentes

Rotação de segredos e chaves de assinatura (JWKS): programado + forçado em um incidente.
Dual-key rollout: Publique o novo par-chave com antecedência (kid2), assine os tokens com ele, mantenha o antigo (kid1) para validação até que a TTL seja esgotada.
Refresh-rotation: Cada troca de refresh → um novo token, o antigo torna-se imediatamente inválido; a repetição é um sinal de comprometimento.
Revocation: para JWT - listas de «jti» retirados por um período curto; para reference tokens - bloqueio imediato em AS.
Cenários de break-glass: créditos estáticos temporários com direitos mínimos e TTL rígido, registo.

Rate limiting, bot-proteção e proteção contra excesso

Limites de três camadas: per-key/per-IP/per-organização.
Burst + sustained: tanque de token/janela deslizante.
Verificações complexas: device fingerprint, sinais comportamentais, geo/ASN anomalias, CAPTCHA apenas para UI.
Lockout/slowdown quando a assinatura/NMAS é superada e tentativas de autenticação precárias.

Logação, métricas e SLO

O conjunto mínimo de logs é 'request _ id', 'cliente _ id', 'sub', 'aud', 'scope', 'decision', 'reason', 'jti', 'ip', 'asn',' latency ',' cota _ state '.

• O sucesso da validação de tokens (%), p95 tempo de verificação.
• Taxa de variação replay duplicada pelo Idempotency-Key.
• Taxa de solicitação de PoP/DPoP/mTLS.
• Erros 'aud/scope' que expiram 'exp', mudanças de tempo (NTP).

• Disponibilidade Auth/AS ≥ 99. 95 %/m; p95 introspection ≤ 50 мс.
• Zero tokens com TTL <60 c vendida (métrica de segurança).
• Menos de 0. 1% de erros 'aud/scope' por dia (qualidade das integrações).

Exemplos de configuração

Envoy: verificação de JWT e audiência

yaml http_filters:
- name: envoy. filters. http. jwt_authn typed_config:
providers:
as:
issuer: https://auth. example. com/
audiences: ["wallet-api"]
remote_jwks:
http_uri:
uri: https://auth. example. com/.well-known/jwks. json cluster: jwks_cluster cache_duration: 600s rules:
- match: { prefix: "/v1/withdraw" }
requires:
provider_and_audiences:
provider_name: as audiences: ["wallet-api"]

NGINX: mTLS к backend

nginx proxy_ssl_server_name on;
proxy_ssl_name wallet. internal;
proxy_ssl_certificate   /etc/nginx/mtls/client. crt;
proxy_ssl_certificate_key /etc/nginx/mtls/client. key;
proxy_ssl_trusted_certificate /etc/nginx/mtls/ca. crt;
proxy_ssl_verify on;
proxy_ssl_verify_depth 2;

Exemplo de cabeçalho da assinatura (webhooks)

X-Signature: t=1730803210,n=ac12...,s=base64(HMAC_SHA256(secret, "POST\n/webhook\nsha256(body)\n1730803210\nac12..."))

O servidor rejeita se 't' tem mais de 300 c, 'n' já se encontrou ou's 'não bate.

Proteção de dados e privacidade

Minimize as marcas (especialmente PII) e o tempo de vida.
Criptografe as marcas sensíveis (JWE) para as integrações de terceiros.
Mask/DLP em logs: não logar o corpo com PAN/PII, os tokens são apenas 'kid '/bandeiras, não o segredo mesmo.

Erros típicos

Tocos de acesso longo e refresh «eternizados».
A ausência de 'aud '/' scope' → o token é multifacetado.
Assinar webhooks sem 'timestamp '/' nonte'.
A verificação do JWT é apenas no aplicativo e não no gaitway (PEP).
Falta de rotações e dual-key rollout.
CORS «» e métodos não seguros permitidos sem controle de cabeçalhos.
Armazenamento de tokens em 'localStorage' sem BFF.

Mapa de tráfego de implementação

1. Inventário API e classificação (público/parceira/interna, sensibilidade).
2. Escolha o modelo AuthN: OAuth2/OIDC para personalizados, mTLS+Client Credentals/HMAC para m2m.
3. Tokens: TTL curtos, «aud» rigoroso, escopos DPoP/PoP para operações críticas.
4. PEP em gaitway: validação do JWT, assinaturas e rate limits até o aplicativo.
5. Anti-replay e idempotidade: timestamp/nonce/Idempotency-Key.
6. Rotações e JWKS: dual-key, automação e alerting.
7. Observabilidade: métricas/SLO, registros de acesso, sinais UEBA.
8. Ensinamentos: retirada da chave de assinatura, fuga de refresh, sobrecarga de quotas.

Especificidades para iGaming/Fintech

Pagamentos/pagamentos: apenas mTLS + PoP/HMAC, escopos rigorosos ('withdraw. create '), idempotency é obrigatório.
Associados (PSP/Provedores de Conteúdo): por-parceiro chaves/certificados, IP/ASN allow-list, quotas individuais e dashboards.
GDPR/PCI DSS: Minimização de marcas, proibição do PII em tokens de terceiros, logação de acesso a recursos sensíveis, regularmente access review.
Anti-abuse: limites comportamentais, geo-controle, proteção contra bónus-abuse em nível API.

FAQ

JWT ou reference tocen?
JWT - desempenho e autonomia; reference - crítica centralizada e facilidade de resposta incidente. Muitas vezes, híbrido, externo, JWT, interno, reference.

A JWE é necessária?
Apenas se o payload contém PII/segredos. Senão, um JWS com marcas mínimas.

É possível viver com chave de API?
Sim, mas apenas com TTL curto, quotas rigorosas, IP-allow-list e assinatura de solicitações. Para os usuários - de preferência OAuth/OIDC.

É obrigatório?
Nem sempre. Mas para as transações high-risk (pagamentos, conclusões) é altamente desejável.

Resultado

A API segura é baseada em tokens de curta duração, escopos de precisão e público, canais de segurança (TLS/mTLS), assinaturas de solicitação e proteção rigorosa anti-replay, reforçados por limites e observabilidade. Adicione rotações automatizadas, dual-key rollout e controle político em gatwees - e sua API se tornará resistente a fugas, repetições e abusos, mantendo a alta produtividade e governabilidade.