Llame a su API con el flujo híbrido

Aprenda a ejecutar el flujo híbrido para que su aplicación pueda usar un token de ID para acceder a la información del usuario y, al mismo tiempo, obtener un código de autorización que pueda intercambiarse por un Token de acceso.

Este tutorial le ayudará a llamar a su propia API con el Flujo híbrido. Si desea obtener más información sobre cómo funciona este flujo y por qué debería usarlo, consulte Flujo híbrido.

Auth0 facilita que su aplicación implemente el Flujo de código de autorización mediante:

• Authentication API: Si prefiere crear su propia solución, siga leyendo para aprender a llamar directamente a nuestra API.

​

Requisitos previos

Antes de comenzar este tutorial:

• Registre su aplicación en Auth0.

  • Seleccione el Tipo de aplicación adecuado.
  • Agregue una URL de callback permitida: {https://yourApp/callback}.
  • Asegúrese de que los Tipos de concesión de su aplicación incluyan Implícito y Código de autorización. Para saber cómo hacerlo, consulte Actualizar tipos de concesión.
  • Si desea que su aplicación pueda usar Tokens de actualización, asegúrese de que los Tipos de concesión de la aplicación incluyan Token de actualización. Para saber cómo hacerlo, consulte Actualizar tipos de concesión. Para obtener más información sobre los Tokens de actualización, consulte Tokens de actualización.

• Registre su API en Auth0

  • Si desea que su API reciba Tokens de actualización para poder obtener tokens nuevos cuando caduquen los anteriores, habilite Permitir acceso sin conexión.

​

Pasos

1. Autorizar al usuario: Solicite autorización al usuario y rediríjalo de vuelta a su aplicación con un código de autorización.
2. Solicitar tokens: Intercambie su código de autorización por tokens.
3. Llamar a la API: Use el Token de acceso obtenido para llamar a su API.
4. Renovar tokens: Use un Token de actualización para solicitar tokens nuevos cuando los actuales expiren.

Opcional: Explorar casos de uso de muestra

​

Autorizar al usuario

Este paso puede incluir uno o más de los siguientes procesos:

• Autenticar al usuario
• Redirigir al usuario a un Proveedor de identidad para gestionar la autenticación
• Comprobar si existen sesiones activas de inicio de sesión único (SSO)
• Obtener el consentimiento del usuario para el nivel de permisos solicitado, a menos que ya se haya otorgado previamente.

Para autorizar al usuario, tu aplicación debe dirigirlo a la URL de autorización.

​

Ejemplo de URL de autorización

Parámetros

Ten en cuenta que, para autorizar a un usuario al llamar a una API personalizada, debes:

• incluir un parámetro audience
• incluir alcances adicionales compatibles con la API de destino

Nombre del parámetro	Descripción
response_type	Indica el tipo de credencial que devolverá Auth0 (code o token). Para este flujo, el valor debe incluir code, pero también puede incluir id_token, token o id_token token. En concreto, id_token devuelve un ID Token y token devuelve un Token de acceso.
response_mode	Especifica el método con el que deben devolverse los parámetros de respuesta. Por motivos de seguridad, el valor debe ser form_post. En este modo, los parámetros de respuesta se codificarán como valores de formulario HTML que se transmiten mediante el método HTTP POST y se codifican en el cuerpo con el formato application/x-www-form-urlencoded.
client_id	El ID de cliente de tu aplicación. Puedes encontrar este valor en la configuración de la aplicación.
redirect_uri	La URL a la que Auth0 redirigirá el navegador después de que el usuario haya concedido la autorización. El código de autorización estará disponible en el parámetro de URL code. Debes especificar esta URL como una URL de callback válida en la configuración de la aplicación. Advertencia: Según la especificación OAuth 2.0, Auth0 elimina todo lo que aparece después del hash e ignora cualquier fragmento.
scope	Especifica los alcances para los que quieres solicitar autorización, que determinan qué claims (o atributos del usuario) quieres que se devuelvan. Deben separarse con un espacio. Puedes solicitar cualquiera de los alcances estándar de OpenID Connect (OIDC) sobre usuarios, como profile o email, claims personalizados que cumplan con un formato con espacio de nombres, o cualquier alcance compatible con la API de destino (por ejemplo, read:contacts). Incluye offline_access para obtener un Token de actualización (asegúrate de que el campo Allow Offline Access esté habilitado en la configuración de la aplicación).
audience	El identificador único de la API a la que tu aplicación quiere acceder. Usa el valor de Identifier en la pestaña Settings de la API que creaste como parte de los requisitos previos de este tutorial.
state	(recomendado) Una cadena alfanumérica arbitraria y opaca que tu aplicación agrega a la solicitud inicial y que Auth0 incluye al redirigir de vuelta a tu aplicación. Para ver cómo usar este valor para evitar ataques de falsificación de solicitudes entre sitios (CSRF), consulta Mitigate CSRF Attacks With State Parameters.
nonce	Una cadena aleatoria criptográficamente segura que tu aplicación agrega a la solicitud inicial y que Auth0 incluye dentro del ID Token, utilizada para evitar ataques de repetición de tokens.
organization	(opcional) ID de la organización que se usará al autenticar a un usuario. Si no se proporciona, y tu aplicación está configurada para Display Organization Prompt, el usuario podrá introducir el nombre de la organización al autenticarse.
invitation	(opcional) ID del ticket de invitación de la organización. Al invitar a un miembro a una Organización, tu aplicación debe gestionar la aceptación de la invitación reenviando los pares clave-valor invitation y organization cuando el usuario acepte la invitación.

Como ejemplo, tu fragmento HTML para la URL de autorización al agregar el inicio de sesión a tu aplicación podría verse así:

​

Respuesta

Si todo sale bien, recibirá una respuesta HTTP 302. Las credenciales solicitadas están codificadas en el cuerpo:

HTTP/1.1 302 Found
Content-Type: application/x-www-form-urlencoded
code=AUTHORIZATION_CODE&
access_token=ey...MhPw
&expires_in=7200
&token_type=Bearer
id_token=eyJ...acA&
state=xyzABC123

Tenga en cuenta que los valores devueltos dependen de lo que haya solicitado como response_type.

Tipo de respuesta	Componentes
code	Código de autorización
id_token	ID Token
token	Token de acceso (más los valores expires_in y token_type)
id_token token	ID Token, Token de acceso (más los valores expires_in y token_type)

Auth0 también devolverá cualquier valor de state que haya incluido en su llamada a la URL de autorización.

El Token de acceso que recibe en esta transacción es solo el primero que recibirá. No recomendamos usarlo para llamar a APIs.

Valide sus tokens antes de guardarlos. Para saber cómo hacerlo, lea Validar tokens de ID y Validar tokens de acceso.

Cuando decodifique y analice su token de ID, observará un claim adicional, c_hash, que contiene un hash del code. Este claim es obligatorio cuando se emite un token de ID al mismo tiempo que un code, y debe validarlo:

1. Con el algoritmo hash especificado en el claim alg del encabezado del ID Token, calcule el hash de los octetos de la representación ASCII del code.
2. Codifique en Base64url la mitad izquierda del hash.
3. Compruebe que el resultado coincida con el valor de c_hash.

​

Solicitar tokens

Ahora que tiene un código de autorización, debe canjearlo por tokens. Con el código de autorización extraído (code) en el paso anterior, deberá enviar una solicitud POST a la URL del token.

El token de acceso que reciba en este paso es el que debe usar para llamar a su API. Asegúrese de mantenerlo separado del token de acceso que recibió en el paso anterior de este tutorial.

​

Ejemplo de POST a la URL del token

Parámetros

Nombre del parámetro	Descripción
grant_type	Configura este valor como authorization_code.
code	El authorization_code obtenido en el paso anterior de este tutorial.
client_id	El ID de cliente de tu aplicación. Puedes encontrar este valor en la configuración de la aplicación.
client_secret	El Secreto del cliente de tu aplicación. Puedes encontrar este valor en la configuración de la aplicación. Para obtener más información sobre los métodos de autenticación de aplicaciones disponibles, consulta Credenciales de la aplicación.
redirect_uri	La URL de callback válida configurada en la configuración de la aplicación. Debe coincidir exactamente con el valor de redirect_uri que se pasó a la URL de autorización en el paso anterior de este tutorial. Ten en cuenta que debe estar codificada en formato URL.

​

Respuesta

Si todo va bien, recibirás una respuesta HTTP 200 con una carga útil que incluye los valores access_token, refresh_token, id_token y token_type:

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer"
}

Valida tus tokens antes de guardarlos. Para saber cómo hacerlo, consulta Validar tokens de ID y Validar tokens de acceso.

Los tokens de ID contienen información del usuario que debe decodificarse y extraerse.

Los tokens de acceso se usan para llamar al endpoint /userinfo de la Authentication API de Auth0 o a otra API. Si llamas a tu propia API, lo primero que deberá hacer es verificar el token de acceso.

Los tokens de actualización se usan para obtener un nuevo token de acceso o token de ID una vez que el anterior haya expirado. refresh_token solo estará presente en la respuesta si incluiste el scope offline_access y habilitaste Allow Offline Access para tu API en el Dashboard.

Los tokens de actualización deben almacenarse de forma segura, ya que permiten que un usuario permanezca autenticado prácticamente de forma indefinida.

​

Llamar a la API

Para llamar a su API desde una aplicación web estándar (o en casos similares en los que las credenciales de la aplicación pueden almacenarse de forma segura), la aplicación debe enviar el Token de acceso obtenido como Bearer Token en el encabezado Authorization de la solicitud HTTP.

​

Tokens de actualización

Ya recibió un token de actualización si ha estado siguiendo este tutorial y completó lo siguiente:

• configuró su API para permitir acceso sin conexión
• incluyó el scope offline_access al iniciar la solicitud de autenticación a través del endpoint de autorización.

Puede usar el Token de actualización para obtener un nuevo token de acceso. Normalmente, un usuario solo necesitará un nuevo token de acceso después de que caduque el anterior o cuando obtenga acceso a un nuevo recurso por primera vez. Es una mala práctica llamar al endpoint para obtener un nuevo token de acceso cada vez que llame a una API, y Auth0 aplica límites de tasa que restringen la cantidad de solicitudes al endpoint que pueden ejecutarse con el mismo token desde la misma IP.

Para actualizar su token, haga una solicitud POST al endpoint /oauth/token de la Authentication API con grant_type=refresh_token.

​

Ejemplo de solicitud POST a la URL del token

Parámetros

Nombre del parámetro	Descripción
grant_type	Establece este valor en refresh_token.
client_id	El ID de cliente de tu aplicación. Puedes encontrar este valor en la configuración de la aplicación.
refresh_token	El token de actualización que se va a usar.
scope	(opcional) Una lista de permisos de scope solicitados, delimitada por espacios. Si no se envía, se usarán los alcances originales; de lo contrario, puedes solicitar un conjunto reducido de alcances. Ten en cuenta que debe estar codificado para URL.

​

Respuesta

Si todo sale bien, recibirás una respuesta HTTP 200 con una carga útil que contiene un nuevo access_token, su duración en segundos (expires_in), los valores de scope otorgados y token_type. Si el scope del token inicial incluía openid, la respuesta también incluirá un nuevo id_token:

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}

Valide sus tokens antes de guardarlos. Para saber cómo hacerlo, consulte Validar tokens de ID y Validar tokens de acceso.

​

Casos de uso de ejemplo

​

Personalizar tokens

Puede usar Rules para cambiar los alcances que se devuelven en los tokens de acceso y/o agregar claims a los tokens de acceso y a los ID Tokens. (Para obtener más información sobre Rules, consulte Auth0 Rules.) Para ello, agregue la siguiente Rule, que se ejecutará después de que el usuario se autentique:

exports.onExecutePostLogin = async (event, api) => {
  // Agregar claims personalizados al Token de acceso y al ID Token
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // Modificar el scope del Token de acceso
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};

Los alcances estarán disponibles en el token una vez que se hayan ejecutado todas las Rules.

Auth0 devuelve la información del perfil en un formato estructurado de claims, tal como lo define la especificación OpenID Connect (OIDC). Esto significa que los claims personalizados agregados a los ID tokens o a los tokens de acceso deben ajustarse a las directrices y restricciones para evitar posibles conflictos.

​

Más información

• Framework de autorización de OAuth 2.0
• Protocolo OpenID Connect
• Tokens