Tipos de tokens

En esta página, se analizan los tipos de tokens usados para la autenticación en las APIs de Google, los servicios de Google Cloud y los servicios creados por el cliente alojados en Google Cloud.

Si accedes a las APIs y a los servicios de Google mediante una biblioteca cliente, puedes configurar las credenciales predeterminadas de la aplicación, y la biblioteca cliente controla los tokens por ti. Este es el método recomendado.

Qué son los tokens

Para la autenticación y la autorización, un token es un objeto digital que contiene información sobre la identidad de la principal que realiza la solicitud y el tipo de acceso para el que está autorizado. En la mayoría de los flujos de autenticación, la aplicación, o una biblioteca que usa la aplicación, intercambia una credencial por un token, que determina a qué recursos puede acceder la aplicación.

Tipos de tokens

En diferentes entornos, se usan diferentes tipos de tokens. En esta página, se describen los siguientes tipos de tokens:

En esta página, no se analizan las claves de API ni los ID de cliente, que se consideran credenciales.

Tokens de acceso

Los tokens de acceso son tokens opacos que se ajustan al framework de OAuth 2.0. Contienen información de autorización, pero no información de identidad. Se usan para autenticar y proporcionar información de autorización a las APIs de Google.

Si usas credenciales predeterminadas de la aplicación (ADC) y las bibliotecas cliente de Cloud o las bibliotecas cliente de las APIs de Google, no es necesario que administres los tokens de acceso. Las bibliotecas recuperan la credencial de forma automática, la intercambian por un token de acceso y lo actualizan según sea necesario.

Accede al contenido del token

Los tokens de acceso son tokens opacos, lo que significa que están en un formato propio; las aplicaciones no pueden inspeccionarlos. Puedes obtener la información de un token de acceso válido (no vencido ni revocado) mediante el extremo tokeninfo de Google OAuth 2.0.

Reemplaza ACCESS_TOKEN por el token de acceso válido y sin vencer.

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

Este comando muestra algo similar al siguiente ejemplo:

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

En la siguiente tabla, se enumeran los campos más importantes que debes comprender:

Campo Descripción
azp El proyecto, el correo electrónico o el ID de la cuenta de servicio de la aplicación que solicitó el token. Este valor solo se incluye si https://www.googleapis.com/auth/userinfo.email se especifica en la lista de alcances.
scope Los permisos de OAuth que se agregaron a este token de acceso. Para los servicios de Google Cloud, se recomienda usar el permiso https://www.googleapis.com/auth/cloud-platform , que incluye todas las APIs de Google Cloud, junto con Identity and Access Management (IAM), que proporciona un control de acceso detallado.
expires_in La cantidad de segundos hasta que el token caduca. Para obtener más información, consulta Ciclo de vida del token de acceso.

Vida útil del token de acceso

De forma predeterminada, los tokens de acceso son útiles durante 1 hora (3,600 segundos). Cuando el token de acceso haya vencido, el código de administración de tokens debe obtener uno nuevo.

Si necesitas un token de acceso con una vida útil más larga o más corta, puedes usar el método serviceAccounts.generateAccessToken para crear el token. Este método te permite elegir la vida útil del token, con un ciclo de vida máximo de 12 horas.

Si deseas extender la vida útil del token más allá de la configuración predeterminada, debes crear una política de la organización que habilite la restricción iam.allowServiceAccountCredentialLifetimeExtension. No puedes crear tokens de acceso con una vida útil prolongada para las credenciales de usuario o las identidades externas. Para obtener más información, consulta Crea un token de acceso de corta duración.

Tokens de ID

Los tokens de ID son tokens web JSON (JWT) que cumplen con la especificación de OpenID Connect (OIDC). Se componen de un conjunto de pares clave-valor llamados reclamaciones.

A diferencia de los tokens de acceso, que son objetos opacos que la aplicación no puede inspeccionar, los tokens de ID deben inspeccionarse y usarse mediante la aplicación. La información del token, como quién firmó el token o la identidad para la que se emitió el token de ID, está disponible para que la use la aplicación.

Para obtener más información sobre la implementación de OIDC de Google, consulta OpenID Connect. Para obtener prácticas recomendadas sobre cómo trabajar con JWT, consulta las prácticas recomendadas actuales del token web JSON.

Contenido del token de ID

Puedes inspeccionar un token de ID válido (no vencido ni revocado) con el extremo tokeninfo de Google OAuth 2.0.

Reemplaza ID_TOKEN por el token de ID válido y sin vencer.

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

Este comando muestra algo similar al siguiente ejemplo:

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

En la siguiente tabla, se describen las reclamaciones de tokens de ID necesarias o de uso común:

Reclamar Descripción
iss El emisor o firmante del token. Para los tokens de ID firmados por Google, este valor es https://accounts.google.com.
azp Opcional. A quién se emitió el token.
aud El público del token. El valor de esta reclamación debe coincidir con la aplicación o servicio que usa el token para autenticar la solicitud. Para obtener más información, consulta la reclamación del token de ID aud.
sub El asunto: el ID que representa al principal que realiza la solicitud.
iat Tiempo de época de Unix cuando se emitió el token.
exp Tiempo de época de Unix cuando vence el token.

Es posible que haya otras reclamaciones según el emisor y la aplicación.

Reclamación del token de ID aud

La reclamación aud describe el nombre del servicio que se creó para invocar este token. Si un servicio recibe un token de ID, debe verificar su integridad (firma), la validez (si caducó) y si la reclamación aud coincide con el nombre que espera. Si no coincide, el servicio debe rechazar el token, ya que podría ser una reproducción destinada a otro sistema.

Por lo general, cuando obtienes un token de ID, usas las credenciales proporcionadas por una cuenta de servicio, en lugar de las credenciales del usuario. Esto se debe a que la reclamación aud para los tokens de ID generados mediante credenciales de usuario está vinculada de forma estática a la aplicación que el usuario usó para autenticarse. Cuando usas una cuenta de servicio para adquirir un token de ID, puedes especificar un valor diferente para la reclamación aud.

Duración del token de ID

Los tokens de ID son válidos hasta por 1 hora (3,600 segundos). Cuando un token de ID vence, debes adquirir uno nuevo.

Validación de token de ID

Cuando tu servicio o aplicación usa un servicio de Google, como Cloud Run, Cloud Functions o Identity-Aware Proxy, Google valida los tokens de ID por ti. En estos casos, Google debe firmar los tokens de ID.

Si necesitas validar tokens de ID dentro de la aplicación, puedes hacerlo, aunque este es un flujo de trabajo avanzado. Para obtener más información, consulta Valida un token de ID.

Tokens web JSON (JWT) autofirmados

Se requieren JWT autofirmados para autenticarse en las APIs implementadas con la puerta de enlace de API. Además, puedes usar JWT autofirmados para autenticarte en algunas APIs de Google sin tener que obtener un token de acceso del servidor de autorización.

Se recomienda crear JWT autofirmados si creas tus propias bibliotecas cliente para acceder a las API de Google, pero es un flujo de trabajo avanzado. Para obtener más información sobre los JWT autofirmados, consulta Crea un token web JSON autofirmado. Para obtener prácticas recomendadas sobre cómo trabajar con JWT, consulta las prácticas recomendadas actuales del token web JSON.

Tokens de actualización

De forma predeterminada, los tokens de acceso y los tokens de ID son válidos durante 1 hora. Un token de actualización es un token especial que se usa para obtener tokens de acceso o tokens de acceso adicionales. Cuando tu aplicación se autentica por primera vez, recibe un token de acceso o un token de ID, junto con un token de actualización. Más adelante, si la aplicación necesita acceder a los recursos otra vez y el token proporcionado anteriormente venció, usa el token de actualización para solicitar un token nuevo. Los tokens de actualización se usan solo para la autenticación de usuarios, como Cloud Identity o Google Workspace.

Los tokens de actualización no tienen una vida útil establecida; pueden vencer, pero, de lo contrario, seguirán siendo utilizables. Para el acceso de usuarios en Google Workspace o Cloud Identity Premium, puedes configurar la duración de la sesión a fin de asegurarte de que un usuario deba acceder de forma periódica para retener el acceso a los servicios de Google Cloud.

Si la aplicación crea y administra sus propios tokens, también debe administrar los tokens de actualización. Para obtener más información, accede a estos vínculos:

Tokens federados

La federación de Workload Identity usa los tokens federados como un paso intermedio. El servicio de tokens de seguridad muestra los tokens federados y no se pueden usar directamente. Se deben intercambiar por un token de acceso mediante el robo de identidad de la cuenta de servicio.

Tokens del portador

Los tokens del portador son una clase general de token que otorga acceso a la parte que posee el token. Los tokens de acceso, los tokens de ID y los JWT autofirmados son tokens del portador.

El uso de tokens del portador para la autenticación se basa en la seguridad proporcionada por un protocolo encriptado, como HTTPS. Si se intercepta un token del portador, una persona que actúa de mala fe puede usarlo para obtener acceso.

Si los tokens del portador no proporcionan suficiente seguridad para tu caso de uso, considera agregar otra capa de encriptación o usar una solución de seguridad de la capa de transporte mutua (mTLS), como BeyondCorp Enterprise, que limita el acceso solo a los usuarios autenticados en un dispositivo de confianza.

¿Qué sigue?