Qué es un bearer token: definición, JWT y seguridad

¿Qué es un bearer token?

Un bearer token (token de portador) es una credencial de acceso que concede lo que autoriza a cualquiera que la presente. Está definido para OAuth 2.0 en la RFC 6750 y viaja en la cabecera HTTP Authorization como Authorization: Bearer <token>. El servidor comprueba el token y permite o rechaza la petición. La posesión es la única prueba exigida, así que un bearer token debe protegerse como una contraseña.

Cómo funciona un bearer token

GET /api/users/me HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

El servidor valida el token buscándolo, verificando su firma o consultando un endpoint de introspección. Si el token ha caducado, está revocado o está mal formado, la RFC 6750 indica que el servidor debe responder 401 y puede incluir el error invalid_token:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

El flujo habitual:

1. El cliente se autentica, por ejemplo mediante un flujo OAuth 2.0 o un inicio de sesión.
2. El servidor de autorización devuelve un access token, normalmente en JSON:

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

3. El cliente guarda el token y lo envía en la cabecera Authorization en cada llamada a la API.
4. La API comprueba el token y sus permisos (scopes) en cada petición.
5. Cuando el token caduca, el cliente usa un refresh token para obtener otro o se autentica de nuevo.

Formatos de bearer token

Tokens opacos

Una cadena aleatoria que no contiene información. El servidor guarda su significado y lo consulta en cada petición, de modo que revocarlo es tan simple como borrar el registro. El coste es una consulta por petición.

Authorization: Bearer 7b3f2e8a-1c4d-4b6a-9e7f-2c8d3a4b5e1f

JWT (JSON Web Tokens)

Un JWT (RFC 7519) es un token firmado y autocontenido: header.payload.signature, cada parte codificada en Base64URL. El payload lleva claims como el usuario, los scopes y la caducidad, y la API puede verificar la firma sin consultar una base de datos. La contrapartida es la revocación: un JWT sigue siendo válido hasta que caduca salvo que mantengas una lista de bloqueo. Recuerda que decodificar un JWT solo lo lee. La confianza viene de verificar la firma. Puedes inspeccionar uno sin riesgo con el decodificador de JWT.

Bearer token frente a otras credenciales

Una clave de API también se envía a menudo como bearer token. La diferencia está en la duración y el alcance: los access tokens bearer deben ser de vida corta y de alcance limitado, y las claves de API normalmente no lo son.

Flujos de OAuth 2.0 que emiten bearer tokens

• Authorization code con PKCE. Para apps con usuarios: el usuario inicia sesión en el proveedor y la app cambia un código por tokens. PKCE protege a los clientes públicos como las apps móviles y las aplicaciones de una sola página.
• Client credentials. Para llamadas de servidor a servidor sin usuario: la app se autentica con su client ID y su secreto y recibe un access token.
• Refresh token. Una credencial de mayor duración que solo sirve para obtener nuevos access tokens, con reglas de almacenamiento más estrictas.
• Device code. Para dispositivos sin navegador, como televisores y herramientas de línea de comandos.

Seguridad de los bearer tokens

Como poseer el token equivale a tener acceso, un token robado funciona para quien lo tenga hasta que caduque.

• Usa siempre TLS. La RFC 6750 exige que los clientes usen siempre TLS al enviar bearer tokens.
• Mantén los tokens fuera de las URL. La especificación solo admite el parámetro de consulta access_token cuando es imposible usar la cabecera o el cuerpo, y lo desaconseja. Las URL acaban en registros y en el historial del navegador.
• Haz que los access tokens duren poco y rota los refresh tokens, para que una fuga tenga una ventana pequeña.
• Pide el scope más estrecho. Un token que lee un perfil no debería poder eliminar la cuenta.
• Valida cada JWT por completo. Verifica la firma con el algoritmo y la clave que tú configuras (nunca con el algoritmo indicado en la cabecera del token) y comprueba después emisor, audiencia y caducidad.
• Guarda los tokens con cuidado. Las apps móviles usan el llavero o keystore del sistema y los servidores un gestor de secretos. Los scripts del navegador pueden leer localStorage, lo que convierte el XSS en una vía de robo. Más en seguridad de APIs.

Errores habituales con los bearer tokens

• Registrar la cabecera Authorization en logs de acceso, proxies o herramientas de errores.
• Emitir access tokens que duran días o semanas, lo que los convierte en claves de API.
• Aceptar un JWT sin comprobar su firma, su emisor o su audiencia.
• Usar un mismo secreto HS256 en varios servicios, de modo que cualquiera que pueda verificar tokens también pueda falsificarlos.
• Poner el token en una cadena de consulta o en el bundle del frontend.

Probar y monitorizar APIs con bearer tokens

La autenticación cambia cómo pruebas una API bajo carga:

• Obtener un token es en sí un endpoint. Si cada usuario virtual pide uno al empezar, también estás probando el servidor de autorización. Decide si eso es lo que quieres.
• Los tokens caducan durante las pruebas largas. Una prueba de 30 minutos con tokens de 15 minutos necesita lógica de renovación en el script.
• Un único token compartido oculta límites y cachés por usuario. Las pruebas realistas usan un token por usuario virtual.
• Comprueba los casos negativos: un token caducado o revocado debe devolver 401 enseguida.

Estos puntos se explican paso a paso en la guía de pruebas de rendimiento de APIs con OAuth 2.0 y en cómo probar APIs protegidas con OAuth usando JMeter (ambos en inglés). Para comprobaciones continuas, la monitorización de APIs de LoadFocus admite cabeceras, bearer tokens OAuth y peticiones encadenadas, y en el plan gratuito las comprobaciones se ejecutan cada 5 minutos. Para lanzar el flujo de tokens bajo carga, consulta las pruebas de carga con JMeter.

Preguntas frecuentes sobre bearer tokens

¿Son seguros los bearer tokens?

Son tan seguros como el trato que les des. Envíalos solo por TLS, mantenlos de vida corta, limita su scope y no los registres nunca. Quien consigue un token válido puede usarlo.

¿Qué diferencia hay entre un bearer token y un JWT?

Bearer describe cómo se usa un token: quien lo presenta obtiene acceso. JWT describe su formato: un token firmado con claims. Un JWT se usa a menudo como bearer token, pero un bearer token también puede ser una cadena aleatoria opaca.

¿Cuánto debe durar un bearer token?

Lo menos que tu aplicación tolere: en los access tokens, normalmente de minutos a una hora, renovados con un refresh token. Cuanto más vive un token, más daño causa una fuga.

¿Se puede revocar un JWT?

No por sí solo, porque la API lo verifica sin consultar a nadie. Los equipos recurren a vidas cortas con rotación de refresh tokens, a una lista de bloqueo o a tokens opacos con introspección cuando importa revocar al instante.

¿Qué hago si me roban un token?

Revócalo junto con su refresh token, cambia cualquier clave de firma que pueda estar expuesta y revisa los registros de acceso en busca de usos desde lugares inesperados.

¿Cómo envío un bearer token con curl?

Añade la cabecera: curl -H "Authorization: Bearer TU_TOKEN" https://api.example.com/me. Con la herramienta curl en línea gratuita puedes probar una petición desde el navegador.