Intercambio del token de actualización con Token Vault

Aprenda cómo una aplicación puede acceder a Token Vault para intercambiar un token de actualización de Auth0 por un token de acceso para invocar APIs externas.

Token Vault admite el intercambio del token de actualización, lo que permite a una aplicación cliente acceder a Token Vault para intercambiar un token de actualización de Auth0 (token sujeto) por el token de acceso de un proveedor externo (token solicitado).

Como los tokens de actualización solo se intercambian a través de un backchannel seguro entre el cliente y el servidor de autorización, nunca se exponen al usuario final. Como resultado, los clientes pueden mantener la sesión de un usuario sin necesidad de que el usuario vuelva a autorizar la conexión.

​

Casos de uso

Entre los casos de uso habituales del intercambio del token de actualización se incluyen:

• Aplicación web: una aplicación web de productividad se conecta a Google Calendar de un usuario y realiza tareas en su nombre, como programar reuniones, sin necesidad de que vuelva a autenticarse.
• Aplicación móvil: una aplicación móvil de galería de fotos se conecta a la cuenta de Google Photos de un usuario y sube fotos a medida que se toman, manteniendo la sesión iniciada al actualizar el token de acceso en segundo plano.

​

Cómo funciona

El siguiente diagrama de secuencia describe de principio a fin cómo llamar a APIs externas mediante el intercambio del token de actualización en Auth0:

Veamos un ejemplo real: un usuario quiere programar una reunión en su Calendario de Google mediante una aplicación web.

​

Requisitos previos

Antes de comenzar, debe configurar el intercambio del token de actualización con Token Vault.

​

Paso 1: Conectar y autorizar el acceso

Para programar la reunión, la aplicación web debe conectarse a Google mediante Auth0 y luego obtener el permiso del usuario para acceder a la API de Google Calendar.

El usuario inicia sesión en la aplicación con Google mediante el flujo de Connected Accounts, que utiliza la My Account API. Si la aplicación usa Organizaciones, el usuario inicia sesión en la organización de destino antes de continuar. Después de que la My Account API valida y completa la solicitud de Connected Accounts, almacena el token de acceso y el Token de actualización de Google con los alcances de calendario solicitados en Token Vault.

​

Paso 2: Realizar el intercambio del token de actualización

Aunque Token Vault no admite la rotación de tokens de actualización, puedes usar DPoP para vincular los tokens emitidos por Auth0 a tu cliente y añadir una capa adicional de seguridad. Para realizar correctamente el intercambio del token de actualización con Token Vault, desactiva Allow Refresh Token Rotation para tu aplicación en el Auth0 Dashboard.

La aplicación puede usar un token de actualización válido de Auth0 para solicitar a Token Vault un token de acceso de Google con los alcances concedidos en el flujo de Connected Accounts. Este proceso permite que la aplicación obtenga un nuevo token de acceso sin necesidad de que el usuario vuelva a autorizar la conexión.

Para realizar el intercambio del token de actualización, la aplicación usa los SDK de Auth0 para enviar una solicitud POST al endpoint /oauth/token con los siguientes parámetros:

curl --request POST 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "subject_token": "<YOUR_AUTH0_REFRESH_TOKEN>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
  "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "connection": "google-oauth2"
}'

Parámetro	Descripción
grant_type	El tipo de concesión. Para Token Vault, configúrelo como urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_id	ID de la aplicación cliente
client_secret	Secreto del cliente. Nota: Puede usar cualquier método de autenticación del cliente para obtener el token de acceso de un proveedor externo.
subject_token_type	Tipo de token de sujeto. Para Token Vault, configúrelo como token de actualización: urn:ietf:params:oauth:token-type:refresh_token
subject_token	El token de actualización de Auth0 que el Servidor de autorización de Auth0 valida para identificar al usuario.
requested_token_type	El tipo de token solicitado. Para Token Vault, configúrelo como el token de acceso del proveedor externo o http://auth0.com/oauth/token-type/federated-connection-access-token
connection	El nombre de la conexión; en este caso, google-oauth2.
login_hint	(Opcional) Use login_hint solo si el usuario tiene varias cuentas de la misma conexión, como una cuenta de Google del trabajo y una cuenta personal de Google. Cuando pasa un valor para login_hint durante el intercambio de tokens, indica explícitamente a cuál de las múltiples cuentas vinculadas del usuario corresponde la solicitud.

​

Paso 3: El Servidor de autorización de Auth0 valida el token de actualización

El Servidor de autorización de Auth0 valida y carga el perfil del usuario asociado al token de actualización de Auth0:

1. Auth0 comprueba si el array connected_accounts del perfil del usuario contiene una cuenta de usuario con el nombre de la conexión indicado en la solicitud de autorización.
2. Si la solicitud de autorización contiene login_hint, Auth0 busca una identidad que coincida tanto con el nombre de la conexión como con login_hint.
3. Si Auth0 no puede encontrar al usuario, devuelve un código de estado 401 con un mensaje de error.

Una vez que el Servidor de autorización de Auth0 valida al usuario, localiza el token de acceso de Google en Token Vault. Si sigue siendo válido, Auth0 devuelve el token de acceso de Google con sus alcances y su tiempo de expiración:

{
  "access_token": "<YOUR_GOOGLE_ACCESS_TOKEN>",
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.addons.execute https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.events.readonly https://www.googleapis.com/auth/calendar.settings.readonly https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
  "expires_in": 1377,
  "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "token_type": "Bearer"
}

Si el token de acceso de Google ha expirado, Auth0 usa el token de actualización de Google almacenado en Token Vault para obtener un nuevo token de acceso de Google con los mismos alcances.

Con el token de acceso de Google, la aplicación llama a la API de Google Calendar en nombre del usuario.

​

Política de expiración del token de actualización del proveedor externo

Auth0 elimina los tokens de actualización del proveedor externo cuando expiran, según la fecha de expiración establecida por dicho proveedor. Los tokens también se eliminan si no se han utilizado en un intercambio de tokens durante más de un año.