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"

Con este comando, se 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 una vida útil máxima de 12 horas.

Si deseas extender la vida útil del token más allá del valor predeterminado, debes crear una política de la organización que habilite la restricción iam.allowServiceAccountCredentialLifetimeExtension. 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.

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

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

Con este comando, se 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:

Reclamación 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, funciones de Cloud Run 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

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

Tu IdP administra la vida útil de los tokens de larga duración. La excepción son los archivos ADC locales, que contienen tokens de actualización que usan las bibliotecas de autenticación a fin de actualizar los tokens de acceso automáticamente para las bibliotecas cliente.

Tokens federados

Workload Identity Federation y Workforce Identity Federation generan tokens federados a partir de identidades federadas.

Los tokens federados se usan de las siguientes maneras:

Los tokens federados que devuelven la federación de identidades para cargas de trabajo y la federación de identidades de personal no son equivalentes a los tokens que devuelve Workload Identity Federation for GKE. Para obtener más información sobre cómo las aplicaciones de Google Kubernetes Engine se autentican en las APIs de Google, consulta Configura las aplicaciones para usar Workload Identity Federation for GKE.

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 Chrome Enterprise Premium, que limita el acceso solo a los usuarios autenticados en un dispositivo de confianza.

¿Qué sigue?