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