Explorar guías rápidas · APIs

Tecnología: APIsCategoría: SeguridadNivel: IntermedioActualizado

Patrones de autenticación de API

Elige e implementa la autenticación de APIs de forma segura entendiendo las claves de API, la autenticación Basic, los tokens Bearer, OAuth 2.0, los JWT, las identidades de servicio, mTLS, la vida útil de los tokens y los fallos habituales en producción.

En esta página
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Clave de API en un encabezado de la solicitud
  5. 2. Preferir encabezados a claves de API en la query string
  6. 3. Autenticación Basic
  7. 4. No incrustar credenciales Basic en las URL
  8. 5. Token de acceso Bearer
  9. 6. No registrar tokens Bearer en los logs
  10. 7. OAuth 2.0 client credentials
  11. 8. Preferir la identidad de carga de trabajo a los secretos de cliente almacenados cuando esté disponible
  12. 9. Flujo OAuth authorization code
  13. 10. PKCE protege los flujos authorization code de los clientes públicos
  14. 11. Patrón de refresh token
  15. 12. Rotar los refresh tokens cuando el proveedor lo admita
  16. 13. Ejemplo de token Bearer JWT
  17. 14. Decodificar los metadatos de un JWT sin darlo por validado
  18. 15. Validar la firma del JWT
  19. 16. Validar el emisor
  20. 17. Validar la audiencia
  21. 18. Validar la caducidad del token
  22. 19. Validar nbf
  23. 20. Validar la autorización después de la autenticación
  24. 21. Autorización basada en scopes
  25. 22. Autorización basada en roles
  26. 23. Autorización a nivel de recurso
  27. 24. El aislamiento de tenants pertenece a la lógica de autorización
  28. 25. Ejemplo de token de servicio a servicio
  29. 26. No solicitar scopes más amplios de lo necesario
  30. 27. Son preferibles los tokens de acceso de corta duración
  31. 28. Almacenar en caché los tokens de acceso de forma responsable
  32. 29. Renovar antes de la caducidad con un margen de seguridad
  33. 30. Evitar avalanchas de renovación de tokens
  34. 31. Autenticación de cliente con mTLS
  35. 32. mTLS puede coexistir con tokens de la capa de aplicación
  36. 33. Proteger las claves privadas
  37. 34. Firma de solicitudes con HMAC
  38. 35. Protección contra replay de solicitudes firmadas
  39. 36. Autenticación en el API gateway
  40. 37. El backend debe saber en qué identidad confiar
  41. 38. No confiar en encabezados de identidad de clientes arbitrarios
  42. 39. Usar correctamente 401 y 403
  43. 40. Devolver WWW-Authenticate cuando corresponda
  44. 41. No devolver detalles sensibles de autenticación
  45. 42. Mantener observables en el servidor los errores de autenticación
  46. 43. Usar IDs de correlación
  47. 44. Probar deliberadamente un token caducado fuera de producción
  48. 45. Probar tokens con audiencia incorrecta
  49. 46. Probar el acceso a un tenant incorrecto
  50. 47. No usar la autenticación como sustituto de la autorización
  51. 48. Preferir estándares a la autenticación personalizada
  52. 49. OpenID Connect sirve para la identidad sobre OAuth 2.0
  53. 50. Token de acceso vs ID token
  54. 51. No usar un refresh token como token de API
  55. 52. Introspección de tokens
  56. 53. La validación de JWT suele ser local
  57. 54. Almacenar en caché las claves de firma con cuidado
  58. 55. Rechazar algoritmos de firma inesperados
  59. 56. No aceptar nunca JWT sin firmar
  60. 57. Almacenar los secretos fuera del control de código fuente
  61. 58. Rotar las credenciales
  62. 59. Admitir rotación con solapamiento cuando sea posible
  63. 60. Evitar una única credencial compartida entre muchos clientes
  64. 61. Limitar la tasa según una identidad estable
  65. 62. Los datos de autenticación no deben usarse como entrada de negocio arbitraria
  66. 63. Tratar los claims del token como entrada de seguridad
  67. 64. Evitar aceptar por accidente tokens de varios emisores
  68. 65. Usar HTTPS en todas partes para las solicitudes que llevan credenciales
  69. 66. Tener cuidado con las redirecciones y los encabezados Authorization
  70. 67. No poner tokens en el código fuente del frontend
  71. 68. Patrón backend-for-frontend
  72. 69. Las sesiones de API basadas en cookies necesitan protección CSRF
  73. 70. Las cookies necesitan atributos seguros
  74. 71. La autenticación y CORS son cosas distintas
  75. 72. La autenticación y el cifrado son cosas distintas
  76. 73. La autenticación y la firma de solicitudes son cosas distintas
  77. 74. Los fallos de autenticación deben denegar por defecto (fail closed)
  78. 75. Evitar credenciales de respaldo personalizadas
  79. 76. Usar con cuidado los health checks
  80. 77. Documentar el contrato de autenticación de la API
  81. 78. Construir una matriz de diagnóstico
  82. Qué significa el resultado
  83. Qué revisar
  84. 401 Unauthorized
  85. 403 Forbidden
  86. Funciona hasta aproximadamente la caducidad del token
  87. Funciona en local pero falla en el servicio desplegado
  88. Se rechaza un JWT válido
  89. Un token válido accede a datos de otro tenant
  90. Notas de producción
  91. Los secretos de autenticación son credenciales de producción
  92. Preferir credenciales de corta duración
  93. Las bibliotecas de autenticación son dependencias de seguridad
  94. La autorización debe estar cerca del recurso protegido
  95. Las APIs multitenant necesitan comprobaciones explícitas del tenant
  96. La rotación de credenciales debe probarse antes de un incidente
  97. Errores comunes
  98. 1. Tratar la decodificación de un JWT como validación
  99. 2. Enviar un ID token a una API
  100. 3. Registrar tokens en bruto en los logs
  101. 4. Compartir una misma clave de API entre muchos clientes
  102. 5. Poner secretos en la query string
  103. 6. Usar tokens Bearer de larga duración porque la renovación resulta incómoda
  104. 7. Validar la autenticación pero no el acceso al tenant/recurso
  105. 8. Aceptar cualquier JWT firmado por un proveedor conocido
  106. 9. Almacenar secretos de cliente en el código del frontend
  107. 10. Construir una autenticación personalizada en lugar de usar estándares consolidados
  108. Siguiente paso
  109. Para profundizar

Problema

Una API necesita saber quién o qué la está llamando antes de permitir el acceso.

Lo difícil no es añadir un encabezado Authorization. Las verdaderas preguntas de ingeniería son:

  • ¿Quien llama es un usuario, un servicio, un script, un dispositivo o un partner?
  • ¿La API necesita solo autenticación, o también autorización delegada?
  • ¿Cuánto tiempo deben vivir las credenciales?
  • ¿Cómo se rotan o se revocan las credenciales?
  • ¿Dónde se almacenan los secretos?
  • ¿Quien llama está dentro de una plataforma de confianza o cruza fronteras entre organizaciones?
  • ¿La API necesita una identidad de cliente fuerte, como mTLS?
  • ¿Los tokens se validan localmente o a través de un servidor de autorización?

El objetivo es elegir el patrón de autenticación más sencillo que encaje con el modelo de confianza, sin crear secretos de larga duración ni seguridad casera frágil.

Respuesta rápida

Usa este modelo de decisión:

Integración sencilla de servidor a servidor con poca complejidad
→ clave de API, si la plataforma la admite de forma segura

Autenticación HTTP heredada/sencilla
→ Basic auth, solo sobre TLS

Token de usuario o de servicio presentado a una API
→ token de acceso Bearer

Un usuario delega el acceso a una aplicación
→ flujo de autorización OAuth 2.0

Servicio a servicio sin usuario
→ OAuth 2.0 client credentials o identidad de carga de trabajo gestionada por la plataforma

Se necesita una identidad de cliente criptográficamente fuerte en la capa TLS
→ mTLS

JWT
→ formato de token, no un protocolo de autenticación por sí mismo

Solicitud típica con un token Bearer:

curl \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.example.com/v1/reports"

No inventes tu propio formato de token ni envíes secretos de larga duración en la query string.

Código / comandos

1. Clave de API en un encabezado de la solicitud

curl \
  --header "X-API-Key: $API_KEY" \
  "https://api.example.com/v1/data"

Úsala cuando la API admita intencionadamente la autenticación con clave de API.

Encaja bien en:

  • integraciones de servicios internos
  • integraciones sencillas con partners
  • acceso de máquinas con poca complejidad

Limitaciones:

  • normalmente representa a la aplicación, no a un usuario final
  • a menudo es de larga duración
  • la revocación y la rotación deben gestionarse explícitamente
  • es de grano grueso salvo que se combine con una política en el servidor

2. Preferir encabezados a claves de API en la query string

Evita:

curl \
  "https://api.example.com/v1/data?api_key=$API_KEY"

Los secretos en la query string pueden filtrarse en:

  • logs de acceso
  • el historial del navegador
  • herramientas de monitoreo
  • proxies inversos
  • datos de referrer

Usa un encabezado de autenticación siempre que la API lo admita.


3. Autenticación Basic

curl \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.example.com/v1/admin"

Esto envía las credenciales mediante autenticación HTTP Basic.

Úsala solo sobre HTTPS.

La autenticación Basic no cifra las credenciales por sí misma; TLS es lo que protege el transporte.


4. No incrustar credenciales Basic en las URL

Evita:

https://user:password@api.example.com

Las credenciales pueden filtrarse a través de logs, el historial, herramientas o diagnósticos.

Usa en su lugar el mecanismo de autorización HTTP.


5. Token de acceso Bearer

curl \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.example.com/v1/reports"

Un token Bearer significa:

quien posea el token puede usarlo

Protégelo como una contraseña.


6. No registrar tokens Bearer en los logs

Mal:

print(headers)

si headers contiene:

Authorization: Bearer ...

En su lugar, registra metadatos seguros:

token presente: sí
emisor del token: emisor esperado
audiencia del token: API esperada
caducidad del token: 2026-10-04T22:00:00Z

No registres el token en sí.


7. OAuth 2.0 client credentials

Úsalo para llamadas de máquina a máquina sin usuario.

Patrón de solicitud de token:

curl \
  --request POST \
  --url "https://auth.example.com/oauth2/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "scope=reports.read"

Respuesta típica:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Después, llama a la API con el token de acceso devuelto.


8. Preferir la identidad de carga de trabajo a los secretos de cliente almacenados cuando esté disponible

En entornos cloud, una identidad administrada o de carga de trabajo (workload identity) a menudo puede obtener tokens sin almacenar un secreto de cliente estático.

Conceptualmente:

identidad de carga de trabajo
→ servidor de autorización / plataforma de identidad cloud
→ token de acceso de corta duración
→ API

Prefiere esto a distribuir secretos de larga duración entre aplicaciones.


9. Flujo OAuth authorization code

Úsalo cuando una aplicación necesita acceso en nombre de un usuario.

Conceptualmente:

Usuario
→ inicio de sesión/consentimiento en el servidor de autorización
→ código de autorización
→ la aplicación canjea el código
→ token de acceso
→ API

Los clientes públicos modernos deben usar PKCE.

No expongas el secreto del canje del código de autorización al código de navegador/móvil cuando el cliente no puede proteger un secreto.


10. PKCE protege los flujos authorization code de los clientes públicos

PKCE usa:

code_verifier
code_challenge

para vincular la solicitud de autorización con el cliente que después canjea el código.

Usa el SDK o la biblioteca que admita el servidor de autorización en lugar de implementar PKCE manualmente, salvo que sea necesario.


11. Patrón de refresh token

Ciclo de vida típico:

token de acceso
→ corta duración

refresh token
→ credencial de mayor duración que se usa para obtener nuevos tokens de acceso

Normalmente, los refresh tokens deben quedarse en la aplicación o el backend de confianza que es dueño de la sesión.

No los expongas de forma amplia a servicios downstream.


12. Rotar los refresh tokens cuando el proveedor lo admita

La rotación de refresh tokens puede reducir el riesgo de reutilización maliciosa (replay).

Un token rotado se sustituye por uno nuevo durante la renovación.

Si se reutiliza un token antiguo, el proveedor puede llegar a detectar un replay sospechoso.

El comportamiento concreto depende del proveedor.


13. Ejemplo de token Bearer JWT

Un JWT suele tener este aspecto:

xxxxx.yyyyy.zzzzz

con tres secciones codificadas en Base64URL:

header.payload.signature

Entre los claims habituales están:

iss
sub
aud
exp
nbf
iat
scope
roles

Un JWT es un formato de token.

No es automáticamente de confianza por el hecho de que se pueda decodificar.


14. Decodificar los metadatos de un JWT sin darlo por validado

Puedes decodificar el payload de un JWT para diagnosticar, pero:

decodificar
!=
validar

La validación debe comprobar la firma y los claims requeridos.

No autorices solicitudes basándote solo en el contenido decodificado del token.


15. Validar la firma del JWT

La validación en el servidor debe usar claves de confianza del proveedor de identidad.

Comprobaciones de validación típicas:

firma
emisor
audiencia
caducidad
not-before (no antes de)
algoritmo de firma permitido
scopes/roles requeridos

Usa una biblioteca de seguridad mantenida.

No implementes manualmente la criptografía de JWT.


16. Validar el emisor

Conceptualmente:

iss == servidor de autorización esperado

Rechaza los tokens de emisores inesperados.

No aceptes cualquier token firmado correctamente salvo que provenga de un emisor de confianza.


17. Validar la audiencia

Conceptualmente:

aud contiene esta API

No se debe aceptar un token destinado a otra API.

La validación de la audiencia impide reutilizar tokens entre servicios no relacionados.


18. Validar la caducidad del token

Comprueba:

exp

y rechaza los tokens caducados.

Puede ser adecuado tolerar un pequeño desfase de reloj, pero debe ser deliberado y limitado.


19. Validar nbf

Si el token contiene:

nbf

no lo aceptes antes de ese momento.

Esto protege contra el uso anticipado de tokens que solo serán válidos en el futuro.


20. Validar la autorización después de la autenticación

La autenticación responde:

¿Quién llama?

La autorización responde:

¿Qué tiene permitido hacer quien llama?

Ejemplo:

usuario autenticado
+
scope: reports.read
→ GET /reports permitido

mismo usuario
sin reports.write
→ POST /reports denegado

No te detengas en la validación del token.


21. Autorización basada en scopes

Ejemplo de scope del token:

reports.read reports.write

Lógica del servidor:

GET /reports
→ requiere reports.read

POST /reports
→ requiere reports.write

Alinea los scopes con las capacidades de la API, no con pantallas arbitrarias de la interfaz.


22. Autorización basada en roles

Ejemplo:

role = ReportAdmin

Los roles pueden ser útiles para permisos de aplicación de grano grueso.

Evita crear un rol para cada endpoint individual.


23. Autorización a nivel de recurso

Incluso con un token válido y el scope correcto, verifica que quien llama puede acceder al recurso solicitado.

Ejemplo:

tenant_id del token = tenant-a
el informe solicitado pertenece a tenant-b
→ denegar

Esto es crítico en las APIs multitenant.


24. El aislamiento de tenants pertenece a la lógica de autorización

No confíes en:

tenantId

procedente únicamente de una query string o del cuerpo de la solicitud.

Deriva o valida la identidad del tenant a partir de un contexto de autenticación de confianza.


25. Ejemplo de token de servicio a servicio

Solicitar el token:

TOKEN="$(
  curl \
    --silent \
    --request POST \
    --url "https://auth.example.com/oauth2/token" \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "client_id=$CLIENT_ID" \
    --data-urlencode "client_secret=$CLIENT_SECRET" \
    --data-urlencode "scope=reports.read" \
  | jq -r '.access_token'
)"

Usar el token:

curl \
  --header "Authorization: Bearer $TOKEN" \
  "https://api.example.com/v1/reports"

En código de producción, usa la biblioteca OAuth admitida por la plataforma en lugar de procesar la respuesta en shell siempre que sea posible.


26. No solicitar scopes más amplios de lo necesario

Mal:

scope=*

Mejor:

scope=reports.read

El mínimo privilegio reduce el radio de impacto si un token queda comprometido.


27. Son preferibles los tokens de acceso de corta duración

Una vida útil corta del token reduce la exposición si el token se filtra.

No compenses las molestias operativas emitiendo tokens Bearer de duración extremadamente larga, salvo que el modelo de seguridad lo exija explícitamente.

Usa en su lugar mecanismos de renovación o de identidad de carga de trabajo.


28. Almacenar en caché los tokens de acceso de forma responsable

Un servicio no necesita solicitar un token nuevo en cada llamada a la API.

Patrón típico:

obtener token
→ almacenarlo en caché hasta que esté cerca de caducar
→ renovar/obtener un token nuevo

Evita ambas cosas:

  • solicitar un token en cada solicitud
  • reutilizar indefinidamente un token caducado

29. Renovar antes de la caducidad con un margen de seguridad

Conceptualmente:

if token.expires_at <= now + refresh_margin:
    token = acquire_new_token()

Usa un margen operativo moderado.

No inventes márgenes grandes y arbitrarios que acorten innecesariamente la vida útil efectiva del token.


30. Evitar avalanchas de renovación de tokens

En servicios con mucha concurrencia, muchos workers pueden detectar la caducidad al mismo tiempo.

Usa:

  • una caché de tokens compartida
  • sincronización/bloqueos
  • lógica de renovación de vuelo único (single-flight)

para evitar una ráfaga de solicitudes de token.


31. Autenticación de cliente con mTLS

Ejemplo:

curl \
  --cert client-cert.pem \
  --key client-key.pem \
  "https://api.example.com/v1/data"

El servidor autentica el certificado de cliente durante la negociación TLS.

Úsalo cuando el modelo de confianza exige una identidad de máquina fuerte.


32. mTLS puede coexistir con tokens de la capa de aplicación

Ejemplo:

mTLS
→ autentica la máquina que llama / el certificado de cliente

Token Bearer
→ transmite la identidad y los permisos de la aplicación/del usuario

Este patrón por capas es habitual en integraciones de mayor confianza.


33. Proteger las claves privadas

Las claves privadas no deben:

  • subirse con commit al control de código fuente
  • incrustarse en imágenes de contenedor
  • almacenarse en configuración en texto plano
  • copiarse en tickets o chats

Usa un almacén de secretos seguro o un sistema de gestión de certificados y claves.


34. Firma de solicitudes con HMAC

Algunas APIs autentican las solicitudes firmando componentes de la solicitud con un secreto compartido.

Conceptualmente:

solicitud canónica
→ HMAC(secreto, solicitud canónica)
→ encabezado de firma

Esto puede proteger la integridad de la solicitud y demostrar la posesión del secreto.

Las reglas exactas de canonicalización dependen de cada API.

No inventes tu propio protocolo HMAC para una API pública cuando existen mecanismos de autenticación estándar.


35. Protección contra replay de solicitudes firmadas

Los protocolos firmados suelen incluir:

marca de tiempo
nonce
hash del cuerpo de la solicitud

El servidor debe rechazar las solicitudes obsoletas o repetidas según el protocolo.

No confíes solo en las firmas si la misma solicitud firmada puede repetirse indefinidamente.


36. Autenticación en el API gateway

Un gateway puede validar:

  • claves de API
  • JWT
  • tokens OAuth
  • certificados mTLS

antes de que el tráfico llegue al backend.

Aun así, diseña con cuidado la autorización en el backend.

No des por hecho que la ubicación en la red basta para que cada solicitud al backend sea de confianza.


37. El backend debe saber en qué identidad confiar

Si un gateway reenvía encabezados de identidad como:

X-User-ID
X-Tenant-ID

el backend debe garantizar que los clientes no puedan saltarse el gateway y falsificar esos encabezados.

Entre los controles típicos están:

  • red privada para el backend
  • acceso solo desde el gateway
  • eliminación/reescritura de encabezados
  • validación de tokens en el backend

38. No confiar en encabezados de identidad de clientes arbitrarios

Mal:

X-User-ID: admin

desde internet pública.

Los encabezados de identidad solo son de confianza si los inserta un intermediario de confianza y están protegidos contra la suplantación.


39. Usar correctamente 401 y 403

Significado habitual:

401 Unauthorized
→ la autenticación falta o no es válida

403 Forbidden
→ quien llama está autenticado pero no tiene permiso

Algunos sistemas varían intencionadamente el comportamiento por motivos de seguridad o privacidad, pero esta es la distinción normal.


40. Devolver WWW-Authenticate cuando corresponda

En APIs con tokens Bearer, una respuesta 401 puede incluir metadatos del desafío de autenticación.

El comportamiento exacto depende de la API y del framework de seguridad.

Usa el comportamiento estándar del framework en lugar de inventar una semántica de errores propietaria.


41. No devolver detalles sensibles de autenticación

Evita respuestas como:

Token firmado correctamente, pero la cuenta de usuario 12345 está deshabilitada en el tenant X

Da el detalle suficiente para que el cliente pueda actuar sin exponer el estado interno de seguridad.


42. Mantener observables en el servidor los errores de autenticación

Registra campos seguros como:

request_id
ID del cliente/de la aplicación
emisor
audiencia
resultado de la comprobación de scopes
resultado de la comprobación de caducidad del token
resultado de la autenticación

No registres:

token de acceso en bruto
secreto de cliente
contraseña
clave privada
refresh token

43. Usar IDs de correlación

Ejemplo de solicitud:

curl \
  --header "X-Correlation-ID: auth-test-123" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.example.com/v1/reports"

Esto ayuda a correlacionar:

solicitud del cliente
logs del gateway
logs de autenticación
logs de la API

44. Probar deliberadamente un token caducado fuera de producción

Entre las pruebas de autenticación útiles están:

token ausente
token mal formado
token caducado
audiencia incorrecta
emisor incorrecto
token válido, falta el scope
token válido, tenant incorrecto

Esto verifica que la API falla de forma segura.


45. Probar tokens con audiencia incorrecta

Un token válido para:

API A

no debería funcionar automáticamente contra:

API B

La validación de la audiencia es esencial en los sistemas distribuidos.


46. Probar el acceso a un tenant incorrecto

En APIs multitenant:

tenant del token = A
tenant del recurso = B

debe denegarse aunque el token sea válido en todo lo demás.

Es una prueba de autorización, no solo de autenticación.


47. No usar la autenticación como sustituto de la autorización

Suposición errónea:

el token es válido
→ permitir todos los endpoints

Modelo correcto:

validar la identidad
→ validar el permiso
→ validar la propiedad del recurso / el tenant

48. Preferir estándares a la autenticación personalizada

Buenas opciones:

  • OAuth 2.0
  • OpenID Connect cuando se necesita inicio de sesión con identidad
  • tokens Bearer estándar
  • mTLS
  • identidad cloud administrada/de carga de trabajo

Evita:

encabezado personalizado con el nombre de usuario cifrado
firma de JWT casera
intercambio de contraseñas propietario

salvo que exista un requisito sólido y revisado.


49. OpenID Connect sirve para la identidad sobre OAuth 2.0

OAuth 2.0 es principalmente un framework de autorización.

OpenID Connect añade conceptos de identidad del usuario como:

ID token
autenticación del usuario
claims de identidad estándar

No envíes un ID token a una API solo porque sea un JWT.

Las APIs normalmente esperan un token de acceso.


50. Token de acceso vs ID token

Usa:

token de acceso
→ llamar a una API

ID token
→ informar a una aplicación cliente sobre el usuario autenticado

No los intercambies salvo que el proveedor de identidad documente explícitamente ese comportamiento.


51. No usar un refresh token como token de API

Los refresh tokens están destinados al servidor de autorización.

La API normalmente debería recibir un token de acceso.


52. Introspección de tokens

Los sistemas de tokens opacos pueden permitir que la API o el gateway llamen a un servidor de autorización para comprobar el estado del token.

Conceptualmente:

token
→ endpoint de introspección
→ activo / inactivo + metadatos

Es útil cuando importa la revocación inmediata y los tokens no son autocontenidos.

Contrapartida:

  • añade una dependencia de red salvo que se almacene en caché

53. La validación de JWT suele ser local

Los tokens de acceso JWT autocontenidos a menudo pueden validarse localmente con claves públicas de confianza.

Ventaja:

  • no hay llamada al servidor de autorización en cada solicitud a la API

Contrapartida:

  • la revocación es menos inmediata salvo que existan mecanismos adicionales

54. Almacenar en caché las claves de firma con cuidado

Los validadores de JWT suelen almacenar en caché las claves públicas/JWKS del proveedor de identidad.

Gestiona correctamente la rotación de claves.

No dejes codificado para siempre un único certificado de firma.

Usa el mecanismo estándar de descubrimiento de claves del framework de seguridad o del proveedor.


55. Rechazar algoritmos de firma inesperados

No aceptes algoritmos arbitrarios declarados por el token.

Configura la biblioteca de validación con los algoritmos en los que la API realmente confía.


56. No aceptar nunca JWT sin firmar

Rechaza los tokens que usen:

alg = none

en APIs protegidas.

Usa bibliotecas JWT maduras con valores predeterminados seguros.


57. Almacenar los secretos fuera del control de código fuente

Prefiere:

  • almacenes de secretos administrados
  • identidad de carga de trabajo
  • variables secretas de CI/CD protegidas
  • configuración de ejecución segura

No hagas commit de:

claves de API
secretos de cliente
claves privadas
refresh tokens
contraseñas

58. Rotar las credenciales

El ciclo de vida de una credencial en producción debe responder:

¿Quién es su propietario?
¿Dónde se almacena?
¿Cuándo caduca?
¿Cómo se rota?
¿Cómo se revoca?
¿Qué se rompe cuando cambia?

Si no se conocen esas respuestas, el diseño de autenticación está incompleto.


59. Admitir rotación con solapamiento cuando sea posible

Rotación más segura:

credencial antigua válida
+
credencial nueva desplegada
→ los clientes migran
→ se revoca la credencial antigua

Esto reduce el riesgo de interrupción en comparación con cambiar todas las dependencias exactamente en el mismo momento.


60. Evitar una única credencial compartida entre muchos clientes

Si 50 servicios comparten la misma clave de API:

no puedes identificar fácilmente
qué servicio hizo cada solicitud

Prefiere una identidad por cliente cuando sea viable operativamente.

Esto mejora:

  • la auditabilidad
  • la revocación
  • la limitación de tasa
  • la respuesta a incidentes

61. Limitar la tasa según una identidad estable

Entre las dimensiones útiles están:

client_id
identidad de la clave de API
tenant
usuario
entidad de servicio (service principal)

No dependas solo de la IP de origen cuando quienes llaman pueden compartir NAT/proxies.


62. Los datos de autenticación no deben usarse como entrada de negocio arbitraria

Ejemplo:

sub = sujeto autenticado

es un claim de identidad.

No reutilices campos no validados de la solicitud del cliente para sobrescribir esa identidad de confianza.


63. Tratar los claims del token como entrada de seguridad

Incluso los claims firmados requieren:

  • validación del emisor
  • validación de la audiencia
  • un esquema esperado
  • una política de autorización

No confíes en un claim solo porque exista.


64. Evitar aceptar por accidente tokens de varios emisores

Si se admiten varios emisores, configúralos explícitamente.

No amplíes la confianza a «cualquier token firmado por un endpoint de claves accesible».


65. Usar HTTPS en todas partes para las solicitudes que llevan credenciales

Las claves de API, las credenciales Basic y los tokens Bearer no deben viajar por HTTP en texto plano.

Redirigir de HTTP a HTTPS no equivale a no enviar nunca la credencial por HTTP.

Llama directamente al endpoint HTTPS.


66. Tener cuidado con las redirecciones y los encabezados Authorization

Si una URL autenticada redirige a otro host, comprende si las credenciales se reenviarán.

No fuerces manualmente encabezados de autorización hacia destinos de redirección no relacionados.


67. No poner tokens en el código fuente del frontend

Un secreto incrustado en:

bundle de JavaScript
binario móvil
aplicación de escritorio

debe considerarse descubrible por el cliente/usuario.

Los clientes públicos no pueden guardar de forma segura secretos de cliente confidenciales de larga duración.


68. Patrón backend-for-frontend

En aplicaciones de navegador, un backend-for-frontend (BFF) puede mantener los tokens sensibles y las credenciales del servidor fuera del JavaScript del navegador.

Conceptualmente:

navegador
→ sesión del BFF
→ backend
→ tokens de las APIs downstream

Úsalo cuando la arquitectura y la plataforma de identidad lo admitan.


69. Las sesiones de API basadas en cookies necesitan protección CSRF

Si el navegador adjunta automáticamente la autenticación mediante cookies, las solicitudes que cambian el estado pueden necesitar defensas contra CSRF.

Los tokens Bearer en encabezados Authorization explícitos tienen un modelo de amenazas distinto en el navegador.

No des por hecho que «autenticado» significa «protegido contra CSRF».


70. Las cookies necesitan atributos seguros

Para las cookies de sesión, considera:

Secure
HttpOnly
SameSite

según los requisitos entre sitios de la aplicación.

No pongas tokens de sesión en cookies legibles desde JavaScript salvo que el diseño lo requiera explícitamente y se entienda el riesgo.


71. La autenticación y CORS son cosas distintas

CORS controla el acceso entre orígenes en el navegador.

No autentica a quien llama.

Una solicitud con cURL puede llamar a una API independientemente de la política CORS del navegador.


72. La autenticación y el cifrado son cosas distintas

La autenticación responde:

¿quién eres?

TLS proporciona:

confidencialidad/integridad del transporte

Usa ambos.


73. La autenticación y la firma de solicitudes son cosas distintas

Token Bearer:

demuestra la posesión del token

Solicitud firmada:

puede vincular la autenticación a componentes de la solicitud

Elige en función del modelo de amenazas y de los estándares del proveedor.


74. Los fallos de autenticación deben denegar por defecto (fail closed)

Si el validador de tokens, la búsqueda de claves o una dependencia de identidad falla de forma inesperada, no permitas la solicitud en silencio.

Los fallos sensibles para la seguridad deben denegar el acceso, salvo que el diseño del sistema, revisado explícitamente, indique otra cosa.


75. Evitar credenciales de respaldo personalizadas

Mal patrón:

falla el token OAuth
→ probar una clave de API de administración compartida y oculta

Las rutas de autenticación de respaldo son fáciles de olvidar y difíciles de auditar.

Mantén explícitas las rutas de autenticación.


76. Usar con cuidado los health checks

Un endpoint de health check público puede no requerir autenticación.

Un endpoint de health check de diagnóstico/administración puede contener detalles sensibles y debe protegerse.

Decide intencionadamente qué información se expone de forma anónima.


77. Documentar el contrato de autenticación de la API

Toda API debe dejar claro:

método de autenticación
emisor del token
audiencia
scopes/roles requeridos
vida útil de las credenciales
mecanismo de renovación
reglas de tenant
comportamiento ante errores

Esto reduce los errores de integración.


78. Construir una matriz de diagnóstico

Para una solicitud autenticada que falla:

No hay encabezado Authorization
→ problema del cliente/de configuración

401 + token caducado
→ renovar/obtener un nuevo token de acceso

401 + emisor/audiencia incorrectos
→ token o configuración de la API incorrectos

403 + token válido
→ problema de autorización/scope/tenant

funciona en local, falla en el servicio desplegado
→ configuración del secreto/la identidad de carga de trabajo/el entorno

fallos intermitentes cerca de la caducidad
→ condición de carrera en la caché/renovación del token

Qué significa el resultado

Patrón Mejor encaje Principal preocupación
Clave de API Acceso sencillo de máquinas Rotación, identidad de grano grueso
Basic auth Integraciones heredadas/sencillas Secreto de larga duración similar a una contraseña
Token Bearer Token de acceso a la API Robo/replay del token
OAuth client credentials Servicio a servicio Identidad del cliente y secreto/identidad de carga de trabajo
OAuth authorization code + PKCE Acceso delegado por el usuario Gestión de redirecciones/sesión/tokens
JWT Formato de token autocontenido Validación correcta de la firma y los claims
Token opaco Token comprobado de forma centralizada Disponibilidad/latencia de la introspección
mTLS Identidad fuerte de máquina/cliente Ciclo de vida de los certificados
Solicitud firmada con HMAC Protocolos firmados de partners/APIs Canonicalización y protección contra replay
Identidad de carga de trabajo Cargas de trabajo cloud/de servidor Configuración de la plataforma/IAM

El principio de diseño clave es:

autenticar la identidad
→ autorizar la capacidad
→ autorizar el recurso

Qué revisar

401 Unauthorized

Comprueba:

  • si falta el encabezado Authorization
  • token mal formado
  • token caducado
  • emisor incorrecto
  • audiencia incorrecta
  • firma no válida
  • fallo del certificado o de la clave de API

403 Forbidden

Es posible que la autenticación haya funcionado.

Comprueba:

  • el scope
  • el rol
  • la propiedad del recurso
  • el tenant
  • la política
  • las restricciones de IP/red

Funciona hasta aproximadamente la caducidad del token

Revisa la lógica de caché y renovación del token.

Puede que el cliente esté reutilizando un token caducado o que varios workers entren en una condición de carrera durante la renovación.

Funciona en local pero falla en el servicio desplegado

Comprueba:

  • las credenciales específicas del entorno
  • la identidad administrada/de carga de trabajo
  • la disponibilidad de los secretos
  • el acceso de red saliente
  • la audiencia/el scope esperados

Se rechaza un JWT válido

Una «sintaxis de JWT válida» no basta.

Comprueba:

  • el emisor
  • la audiencia
  • la clave de firma
  • el algoritmo
  • exp
  • nbf
  • el scope/rol requerido

Un token válido accede a datos de otro tenant

Es un defecto de autorización/aislamiento.

La autenticación funcionó, pero la autorización a nivel de recurso falta o es incorrecta.

Notas de producción

Los secretos de autenticación son credenciales de producción

Trátalos con el mismo cuidado que las contraseñas.

No los expongas en:

  • logs
  • capturas de pantalla
  • tickets
  • control de código fuente
  • historial de la shell
  • bundles del lado del cliente

Preferir credenciales de corta duración

Los tokens de acceso de corta duración y la identidad de carga de trabajo reducen el impacto del robo de credenciales.

Los secretos estáticos de larga duración aumentan la carga de la rotación y de la respuesta a incidentes.

Las bibliotecas de autenticación son dependencias de seguridad

Usa bibliotecas mantenidas de la plataforma o del framework.

Mantenlas actualizadas con parches y evita la criptografía o el análisis de tokens escritos a mano.

La autorización debe estar cerca del recurso protegido

La validación en el gateway es útil, pero el servicio debe seguir aplicando los permisos que importan para sus datos y sus reglas de negocio.

Las APIs multitenant necesitan comprobaciones explícitas del tenant

Nunca des por hecho que un token válido puede acceder a cualquier tenant representado en los parámetros de la solicitud.

La rotación de credenciales debe probarse antes de un incidente

Si una clave no puede rotarse sin tiempo de inactividad, el diseño de autenticación es frágil desde el punto de vista operativo.

Errores comunes

1. Tratar la decodificación de un JWT como validación

Cualquiera puede decodificar el payload de un JWT.

La confianza requiere validar la firma y los claims.

2. Enviar un ID token a una API

Usa el token de acceso destinado a esa API.

3. Registrar tokens en bruto en los logs

Los logs suelen tener una retención y un acceso amplios.

4. Compartir una misma clave de API entre muchos clientes

Esto perjudica la auditabilidad y la revocación.

5. Poner secretos en la query string

Se filtran con facilidad.

6. Usar tokens Bearer de larga duración porque la renovación resulta incómoda

Esto aumenta el impacto de un compromiso.

7. Validar la autenticación pero no el acceso al tenant/recurso

Esto provoca defectos de seguridad, incluso entre tenants.

8. Aceptar cualquier JWT firmado por un proveedor conocido

El emisor y la audiencia deben coincidir igualmente con la política de confianza de la API.

9. Almacenar secretos de cliente en el código del frontend

Los clientes públicos no pueden mantener secretos confidenciales.

10. Construir una autenticación personalizada en lugar de usar estándares consolidados

Los casos límite de seguridad se acumulan rápidamente.

Siguiente paso

Usa el tipo de quien llama y el modo de fallo para elegir la siguiente acción.

  • Integración sencilla de máquinas → considera una clave de API solo si la rotación y la granularidad de la identidad son aceptables.
  • Servicio a servicio en una plataforma de identidad moderna → prefiere OAuth client credentials o la identidad de carga de trabajo.
  • Acceso a la API delegado por el usuario → usa el flujo authorization code con PKCE cuando corresponda.
  • La API recibe JWT → valida la firma, el emisor, la audiencia y los claims de tiempo, y después los scopes/roles.
  • Un token válido recibe 403 → inspecciona la política de autorización, el scope, el tenant y la propiedad del recurso.
  • Los tokens caducan de forma intermitente → inspecciona el comportamiento de la caché/renovación y la concurrencia.
  • Se necesita una identidad de máquina fuerte → evalúa mTLS.
  • Los secretos son difíciles de rotar → rediseña el ciclo de vida de las credenciales antes de escalar la integración.
  • Necesitas reproducir manualmente el comportamiento de autenticación → usa Referencia rápida de cURL.
  • La autenticación funciona pero la API sigue fallando → pasa a Diagnosticar solicitudes de API.

← Todas las guías rápidas