Autenticación de API: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT es un estándar para aplicaciones cliente e integraciones de servidores con autorización compleja (scopes/roles/tenants), SSO y tokens TTL cortos.
Las firmas HMAC son la mejor opción para webhooks y llamadas de afiliados simples «server→server» con verificación determinista y protección antirreplay rígida.
Refuerce la seguridad: mTLS o DPoP (sender-constrained tokens), TTL corto (5-15 min), rotación de claves (JWKS), tokens refresh con rotación/anti-reuse, validación estricta 'aud/iss/amb/nbf/kid' y policy-as-code en gateway.

1) Mapa de soluciones: ¿Dónde aplicar

2) OAuth2/OIDC: flujos y clientes

2. 1 Hilos

Authorization Code + PKCE (Web/Mobile): protege el código de autorización de la intercepción.
Credentials del cliente: server↔server sin usuario; scopes - mínimo necesario.
Código de dispositivo: para dispositivos sin navegador.
Refresh Token: sólo para clientes de confianza; rotar y activar la detección reuse.

2. 2 Tipos de cliente

Confidential (servidores, BFF): guardan secretos; utilice mTLS.
Public (SPA/mobile): el secreto no se puede almacenar → PKCE, DPoP, TTL cortos y scopes limitados.

3) JWT: estructura, plazos, verificación

3. 1 Campos (claims)

Obligatorios: 'iss', 'sub', 'aud', 'amb', 'iat', 'nbf', 'jti', 'scope '/' permissions',' tenant '(si multiarriendo),' kid '.

3. 2 Plazos de vida

Access token: 5-15 minutos.
Refresh token: días/semanas, rotar en cada intercambio; si vuelve a presentar el antiguo, bloqueamos la sesión.
Clock skew: tolerancia ≤ 60 segundos.

3. 3 JWKS y llaves

El almacenamiento de claves en KMS/Vault, 'kid' es obligatorio.
Dos claves activas (rolling), relanzamiento una vez cada 60-90 días o en caso de incidente.
Cash JWKS en gateway ≤ 5 minutos, con discapacidad automática.

3. 4 Verificación en gateway/servicios

Consulta: firma, 'aud' (servicios admitidos), 'iss',' amb/nbf ', lista de bloqueos (revocación).
No confíe en los campos del cuerpo sin verificar la firma; ignorar 'alg = none'.

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

4) Enlace de token al cliente: mTLS, DPoP

mTLS (certificados de cliente TLS): el token sólo se emite y valida si hay un certificado de cliente → el token es inútil fuera del conjunto «clave + certificado».
DPoP (Demonstration of Proof-of-Possession): el cliente firma cada solicitud con una clave única → protección contra el replay y el robo de tokens en clientes públicos.
Para rutas críticas (mutaciones de pago) es requerir uno de los mecanismos.

5) Autorización: scopes, roles, ABAC

Scopes - acciones mínimas ('payments: write', 'payouts: status: read').
Roles - Unidades para Almirantes; no los use directamente sin scopes.
ABAC - atributos en token ('tenant', 'country', 'kyc _ level', 'risk _ flags') → políticas en gateway/OPA.
Directiva a nivel de ruta/campo (GraphQL) y a nivel de operación de dominio (NAT/gRPC).

6) Firmas HMAC: webhooks y socios

6. 1 Concepto

Cada integración tiene su propio secreto.

Firma sobre la cadena canónica: 'timestamp + '\n' + método + '\n' + path + '\n' + sha256 (cuerpo)'

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

Ventana de tiempo: ≤ 300 segundos; solicitudes con 'X-Timestamp' vencido/futuro para rechazar.
Idempotencia: almacenar 'X-Event-Id' en TTL (24 h) - descartar duplicados.

6. 2 Mejores prácticas

Secretos en KMS/Vault, rotación cada 90 días.
Para los clientes públicos, HMAC no es adecuado (el secreto se filtra); use OAuth2/DPoP.

7) Protección contra replay, fuerza bruta y fugas

Nonce/' jti 'para operaciones sensibles; lista negra de identificadores usados.
Tasa/quotas: por clave/cliente/tenante/ruta; operaciones «caras» - cuotas separadas.
IP/ASN/Geo allow-lists para socios y webhooks.
Content-type allow ('aplicación/json'), el límite de tamaño del cuerpo.
Enmascarar PII en los logs; prohibición de lógica de tokens/secretos.

8) Errores y respuestas (formato único)

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

• '401' - No/No Token (WWW-Authenticate).
• '403' - derechos insuficientes (scope/ABAC).
• '429' - límites/cuotas.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) Políticas de fechas y períodos de sesiones

Acceso ≤ 15 minutos; Refresh - rotación + reuse detection (archivado antiguo - revocación de la sesión).
Webhooks HMAC: firmas TTL ≤ 5 min; reenvío con backoff exponencial.
Revocación de sesión/clave → acceso inmediato a la lista de revocación (caché en gateway ≤ 1 min).

10) Observabilidad y auditoría

Correlación por 'trace _ id '/' span _ id'.
Métricas: tasa de éxito automático, '401/403/429', latencia OIDC/JWKS, frecuencia de rotación, reuse refresh, proporción de tráfico DPoP/mTLS.
Auditoría-registro: «¿quién, cuándo, con qué 'sub/tenant/scope' causó eso», cambios de claves/secretos, firmas fallidas de HMAC.

11) Incrustación en la API Gateway

Validación JWT (caché JWKS) y OPA/ABAC en la puerta de enlace.
Perfiles mTLS para clientes/socios de confianza.
Verificación HMAC de webhooks en edge (antes de los servicios internos).
Rate/Quota pólizas, circuit-breaker en OIDC proveedor (caché JWK).
Características: desactivar rápidamente el cliente/clave, cambiar el algoritmo de firma.

12) Mini Snippets

Pseudo: verificación 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: verificación de 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)

Ejemplo de políticas scope (idea OPA/Rego)

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

13) Playbucks de incidentes

Fuga de clave privada/firma JWT: reinicio de claves, actualización de JWKS, desactivación inmediata de la antigua ('kid' → deny), discapacidad refresh, logout forzado.
Sustitución de webhooks: rotación de secretos, IP allow-list, amplificación de la ventana 'X-Timestamp', retransmisión de eventos perdidos.
Replay/brutforce: habilitar DPoP/mTLS en rutas críticas, estrechamiento de cuotas, bloques de tiempo por IP/ASN, habilitar la lista de bloques 'jti'.
OIDC de salida: degradación de tokens en caché (grace), circuit-breaker del proveedor, notificación al cliente.

14) Hojas de comprobación de implementación

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL: Acceso ≤ 15 min, Refresh con rotación y reuse detection
• JWKS: dos claves activas, 'kid', caché ≤ 5 min
• Webhooks: HMAC v1, 'X-Timestamp', 'X-Event-Id', ventana ≤ 300 segundos, idempotencia
• Sender-constrained: mTLS/DPoP en rutas críticas
• ABAC/OPA: scopes + tenant/risk en las políticas de gateway
• Rate/Quota и 429; IP/ASN allow-lists para socios
• Auditoría y alertas (401/403/429, reuse refresh, firmas HMAC)

• No lógica tokens/secretos/cuerpos completos de tarjetas
• Enmascaramiento PII; Soporte DSAR; la vida útil de los registros es limitada

15) Anti-patrones

'alg = none' o confianza en un token sin verificación de firma/JWKS.
Tokens de acceso de larga vida (horas/día).
Un secreto HMAC compartido en todos los socios.
Webhooks sin tiempo de espera/idempotencia.
Refresh-tokens sin rotación y sin detección reuse.
Falta de validación 'aud '/' iss' y' kid '-rotección.
Almacenar secretos en variables de entorno sin KMS/Vault.

16) NFT/SLO (puntos de referencia)

Disponibilidad OIDC/JWKS ≥ 99. 95% (la caché edge reduce la dependencia).
JWT validación suplemento en gateway ≤ 2-5 ms p95.
Errores de autenticación ('401') ≤ 0. 5% del tráfico total (excluidos los bots).
Webhooks firmados: porcentaje de ≥ verificados con éxito 99. 9%, retraso medio de entrega ≤ 3 s.

Resumen

Combine los mecanismos: OAuth2/OIDC + JWT para usuarios y escenarios de servidores ricos, HMAC para webhooks/partners simples, y para operaciones críticas, mTLS/DPoP. Mantenga el TTL corto, la rotación de claves (JWKS), las estrictas políticas ABAC/OPA, proteja los contornos de replay y fugas, y automatice todo a nivel de API Gateway. Así que la autenticación será predecible, escalable y segura, sin comprometer UX y monetización.