Llame a su API mediante el Flujo de autorización de dispositivo

Aprenda a llamar a su API desde un dispositivo con capacidad de entrada limitada mediante el Flujo de autorización de dispositivo.

Este tutorial te ayudará a llamar a tu propia API desde un dispositivo con entrada limitada mediante el Flujo de autorización de dispositivo. Si quieres obtener más información sobre cómo funciona el flujo y por qué deberías usarlo, consulta Flujo de autorización de dispositivo.

Auth0 facilita la implementación del flujo de autorización de dispositivo en tu aplicación mediante:

• Authentication API: Sigue leyendo para aprender a llamar directamente a nuestra API. Para una experiencia interactiva, consulta Entorno de pruebas del flujo de dispositivo.

​

Requisitos previos

Antes de comenzar este tutorial:

• Consulte las limitaciones (a continuación) para asegurarse de que el Flujo de autorización de dispositivo sea adecuado para su implementación.

• Registre la aplicación en Auth0.

  • Seleccione Native en Application Type.
  • Si es necesario, configure Allowed Web Origins. Puede usar esta opción para permitir localhost como origen durante el desarrollo local o para establecer un origen permitido para software de TV específico con una arquitectura sujeta a CORS (por ejemplo, HTML5 + JS). La mayoría de las aplicaciones no usarán esta configuración.
  • Asegúrese de que la opción OIDC Conformant esté habilitada. Esta configuración se encuentra en el Dashboard, en Applications > Application > Advanced Settings > OAuth.
  • Asegúrese de que los Grant Types de la aplicación incluyan Device Code. Para saber cómo hacerlo, consulte Actualizar tipos de concesión.
  • Si desea que la aplicación pueda usar tokens de actualización, asegúrese de que los Grant Types de la aplicación incluyan Refresh Token. 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.

• Configure y habilite al menos una conexión para la aplicación: Conexiones de base de datos, Conexiones sociales

• Registre su API en Auth0

  • Si desea que su API reciba tokens de actualización para poder obtener nuevos tokens cuando caduquen los anteriores, habilite Allow Offline Access. Para obtener más información sobre los tokens de actualización, consulte Tokens de actualización.

• Configure los ajustes del código de usuario del dispositivo para definir el conjunto de caracteres, el formato y la longitud de su código de usuario generado aleatoriamente.

​

Pasos

1. Solicitar código de dispositivo (flujo de dispositivo): Solicite un código de dispositivo que el usuario pueda usar para autorizar el dispositivo.
2. Solicitar activación del dispositivo (flujo de dispositivo): Solicite que el usuario autorice el dispositivo con su portátil o smartphone.
3. Solicitar tokens (flujo de dispositivo): Consulte periódicamente el endpoint de token para solicitar un token.
4. Autorizar al usuario (flujo del navegador): El usuario autoriza el dispositivo para que este pueda recibir tokens.
5. Recibir tokens (flujo de dispositivo): Después de que el usuario autorice correctamente el dispositivo, reciba los tokens.
6. Llamar a la API (flujo de dispositivo): Use el Token de acceso obtenido para llamar a su API.
7. Renovar tokens (flujo de dispositivo): Use un Token de actualización para solicitar nuevos tokens cuando los existentes expiren.

Opcional: Explorar casos de uso de ejemplo.

Opcional: Solucionar problemas.

​

Solicitar código de dispositivo

Una vez que el usuario haya iniciado la aplicación del dispositivo y quiera autorizarlo, deberá obtener un código de dispositivo. Cuando el usuario inicie su sesión en el dispositivo con navegador, este código quedará vinculado a esa sesión.

Para obtener el código de dispositivo, su aplicación debe solicitar un código en la URL del código de dispositivo, incluido el ID de cliente.

​

Ejemplo de POST a la URL de código de dispositivo

Parámetros del código de dispositivo

Ten en cuenta que, al solicitar un código de dispositivo para llamar a una API personalizada:

• debes incluir un parámetro audience
• puedes incluir alcances adicionales admitidos por la API de destino

Si tu aplicación solo quiere un Token de acceso para obtener información sobre el usuario autenticado, no se requiere ningún parámetro audience.

Nombre del parámetro	Descripción
client_id	El ID de cliente de tu aplicación. Puedes encontrar este valor en la configuración de la aplicación.
scope	Los alcances para los que quieres solicitar autorización. Deben estar separados por espacios. Puedes solicitar cualquiera de los alcances estándar de OIDC sobre usuarios, como profile y email, claims personalizados que cumplan con un formato con espacio de nombres, o cualquier alcance admitido por la API de destino (por ejemplo, read:contacts). Incluye openid para obtener un ID Token o para poder usar el endpoint /userinfo y recuperar información del perfil del usuario. 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 API). Ten en cuenta que debe estar codificado como URL.
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. Ten en cuenta que debe estar codificado como URL.

​

Respuesta del código de dispositivo

Si todo sale bien, recibirás una respuesta HTTP 200 con una carga útil que contiene los valores device_code, user_code, verification_uri, expires_in, interval y verification_uri_complete:

{
  "device_code": "Ag_EE...ko1p",
  "user_code": "QTZL-MCBW",
  "verification_uri": "https://accounts.acmetest.org/activate",
  "verification_uri_complete": "https://accounts.acmetest.org/activate?user_code=QTZL-MCBW",
  "expires_in": 900,
  "interval": 5
}

• device_code es el código único del dispositivo. Cuando el usuario acceda a verification_uri desde un dispositivo con navegador, este código se vinculará a su sesión.
• user_code contiene el código de usuario que debe introducirse en verification_uri para autorizar el dispositivo.
• verification_uri contiene la URL que el usuario debe visitar para autorizar el dispositivo.
• verification_uri_complete contiene la URL completa que el usuario debe visitar para autorizar el dispositivo. Esto permite que su aplicación incorpore user_code en la URL, si así lo desea.
• expires_in indica la duración (en segundos) de device_code y user_code.
• interval indica el intervalo (en segundos) con el que la aplicación debe consultar la URL del token para solicitar un token.

Puede configurar el conjunto de caracteres, el formato y la longitud de su código de usuario generado aleatoriamente en la Configuración del Tenant.

Para evitar ataques de fuerza bruta, aplicamos los siguientes límites a user_code:

Longitud mínima:

• Letras BASE20: 8 caracteres
• Números: 9 caracteres

Longitud máxima:

• 20 caracteres (incluidos los guiones y los espacios, que pueden añadirse como separadores para mejorar la legibilidad)

Tiempo de expiración:

• 15 minutos

​

Solicitar la activación del dispositivo

Una vez que hayas recibido un device_code y un user_code, debes pedirle al usuario que vaya a la verification_uri desde su portátil o smartphone e introduzca el user_code:

El device_code no está pensado para el usuario y no debe mostrarse durante la interacción para evitar confundirlo.

Al crear una CLI, puedes omitir este paso y abrir el navegador directamente con verification_uri_complete.

​

Solicitar tokens

Mientras espera a que el usuario active el dispositivo, comience a sondear la URL del token para solicitar un Token de acceso. Con el intervalo de sondeo (interval) extraído del paso anterior, deberá realizar un POST a la URL del token enviando el device_code.

Para evitar errores debidos a la latencia de la red, debe comenzar a contar cada intervalo después de recibir la respuesta de la última solicitud de sondeo.

​

Ejemplo de solicitud POST de token a la URL del token

Parámetros de la solicitud de token

Nombre del parámetro	Descripción
grant_type	Establézcalo en “urn:ietf:params:oauth:grant-type:device_code”. Este es un tipo de concesión de extensión (como se define en la sección 4.5 de RFC6749). Tenga en cuenta que debe codificarse como URL.
device_code	El device_code recuperado en el paso anterior de este tutorial.
client_id	El ID de cliente de su aplicación. Puede encontrar este valor en la configuración de la aplicación.

​

Respuestas de token

Mientras espera a que el usuario autorice el dispositivo, es posible que reciba varias respuestas HTTP 4xx:

Autorización pendiente

Verá este error mientras espera a que el usuario realice alguna acción. Continúe con el sondeo usando el intervalo sugerido obtenido en el paso anterior de este tutorial.

HTTP/1.1 403 Forbidden
{
  "error": "authorization_pending",
  "error_description": "..."
}

Vaya más despacio

Está realizando el sondeo demasiado rápido. Vaya más despacio y use el intervalo sugerido obtenido en el paso anterior de este tutorial. Para evitar que se produzca este error debido a la latencia de la red, debe empezar a contar cada intervalo después de recibir la respuesta a la última solicitud de sondeo.

HTTP/1.1 429 Too Many Requests
{
  "error": "slow_down",
  "error_description": "..."
}

Token vencido

El usuario no autorizó el dispositivo con la suficiente rapidez, por lo que el device_code venció. Su aplicación debe notificarle que el flujo venció e indicarle que lo inicie de nuevo.

El error expired_token se devolverá exactamente una vez; después de eso, se devolverá invalid_grant. Su dispositivo debe detener el sondeo.

HTTP/1.1 403 Bad Request
{ 
  "error": "expired_token",
  "error_description": "..."
}

Acceso denegado

Por último, si se deniega el acceso, recibirá:

HTTP/1.1 403 Forbidden
{
  "error": "access_denied",
  "error_description": "..."
}

Esto puede ocurrir por diversos motivos, entre ellos:

• el usuario se negó a autorizar el dispositivo
• el servidor de autorización denegó la transacción
• una Rule configurada denegó el acceso (Para obtener más información, consulta Auth0 Rules.)

​

Autorizar al usuario

El usuario escaneará el código QR o, de lo contrario, abrirá la página de activación e introducirá el código de usuario:

Se mostrará una página de confirmación para que el usuario confirme que se trata del dispositivo correcto:

El usuario completará la transacción iniciando sesión. Este paso puede incluir uno o más de los siguientes procesos:

• Autenticar al usuario;
• Redirigir al usuario a un Proveedor de identidad para encargarse de la autenticación;
• Comprobar si hay sesiones activas de SSO;
• Obtener el consentimiento del usuario para el dispositivo, a menos que ya lo haya otorgado previamente.

Tras autenticarse correctamente y otorgar el consentimiento, se mostrará la pantalla de confirmación:

En este punto, el usuario se ha autenticado y el dispositivo ha sido autorizado.

​

Recibir tokens

Mientras el usuario se autentica y autoriza el dispositivo, la aplicación del dispositivo sigue consultando la URL del token para solicitar un token de acceso.

Una vez que el usuario haya autorizado correctamente el dispositivo, recibirás una respuesta HTTP 200 con una carga útil que contiene los valores access_token, refresh_token (opcionalmente), id_token (opcionalmente), token_type y expires_in:

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

Valide sus tokens antes de guardarlos. Para saber cómo hacerlo, lea Validate ID Tokens y Validate Access Tokens.

Los tokens de acceso se usan para llamar al endpoint /userinfo de la API de autenticación de Auth0 o a otra API. (Para obtener más información sobre los tokens de acceso, lea Access Tokens.) Solo podrá usar el Token de acceso para llamar a /userinfo si incluyó el scope openid. Si llama a su propia API, lo primero que deberá hacer es verificar el Token de acceso.

ID Tokens contienen información del usuario que debe decodificarse y extraerse. (Para obtener más información sobre los ID Token, lea ID Tokens.) El id_token solo estará presente en la respuesta si incluyó el scope openid.

tokens de actualización se usan para obtener un nuevo Token de acceso o ID Token después de que el anterior haya expirado. (Para obtener más información sobre los tokens de actualización, lea Refresh Tokens.) El refresh_token solo estará presente en la respuesta si incluyó el scope offline_access y habilitó Allow Offline Access para su API en el Dashboard.

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

​

Llama a tu API

Para llamar a tu API, la aplicación debe enviar el Token de acceso obtenido como un Bearer Token en el encabezado Authorization de la solicitud HTTP.

​

Tokens de actualización

Ya has recibido un Token de actualización si has seguido este tutorial y has completado lo siguiente:

• configuraste tu API para permitir el acceso sin conexión
• incluiste el scope offline_access cuando iniciaste la solicitud de authentication a través del endpoint de autorización

Puedes 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 el anterior expire o cuando obtenga acceso a un recurso nuevo por primera vez. No es una buena práctica llamar al endpoint para obtener un nuevo Token de acceso cada vez que llamas a una API, y Auth0 aplica límites de frecuencia que limitarán la cantidad de solicitudes al endpoint que pueden ejecutarse con el mismo token desde la misma IP.

Para renovar tu token, haz una solicitud POST al endpoint /oauth/token de la Authentication API, con grant_type=refresh_token.

​

Ejemplo de POST de un Token de actualización a la URL del token

Parámetros de la solicitud de Token de actualización

Nombre del parámetro	Descripción
grant_type	Establezca este valor en “refresh_token”.
client_id	El ID de cliente de su aplicación. Puede encontrar este valor en la configuración de la aplicación.
client_secret	El Secreto del cliente de su aplicación. Puede 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, puede solicitar un conjunto reducido de alcances. Tenga en cuenta que debe codificarse como URL.

​

Respuesta del Token de actualización

Si todo va bien, recibirás una respuesta HTTP 200 con una carga útil que incluye un nuevo access_token, id_token (opcionalmente), la duración del token en segundos (expires_in), los valores de scope concedidos y token_type:

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

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

​

Casos de uso de ejemplo

​

Detectar el uso del Flujo de autorización de dispositivo

Puede usar Rules para detectar si la transacción actual utiliza el Flujo de autorización de dispositivo. (Para obtener más información sobre Rules, consulte Auth0 Rules.) Para ello, verifique la propiedad protocol del objeto context:

function (user, context, callback) {
   if (context.protocol === 'oauth2-device-code') {
      ...
   }
 
   callback(null, user, context);
}

​

Implementaciones de ejemplo

• Entorno de pruebas del flujo de autorización de dispositivo
• AppleTV (Swift): Aplicación sencilla que muestra cómo se puede usar Auth0 con el Flujo de autorización de dispositivo en un AppleTV.
• CLI (Node.js): Implementación de ejemplo de una CLI que usa el Flujo de autorización de dispositivo en lugar del Flujo de código de autorización. La principal diferencia es que tu CLI no necesita alojar un servidor web ni escuchar en un puerto.

​

Solución de problemas

Los registros del inquilino se generan para cualquier interacción que tenga lugar y pueden usarse para solucionar problemas. Para obtener más información, consulte Logs.

​

Códigos de error

Código	Nombre	Descripción
fdeaz	Error en la solicitud de autorización del dispositivo
fdeac	Error en la activación del dispositivo
fdecc	El usuario canceló la confirmación del dispositivo
fede	Error en el intercambio	Código de dispositivo por token de acceso
sede	Intercambio exitoso	Código de dispositivo por token de acceso

​

Limitaciones

Para usar el Flujo de autorización de dispositivo, los dispositivos deben:

• Admitir Server Name Indication (SNI) cuando se usan dominios personalizados
• Tener un tipo de aplicación de Auth0 Native
• Tener el método de autenticación del endpoint de token establecido en None
• Ser conformes a OIDC
• No haberse creado mediante Dynamic Client Registration

Además, el Flujo de autorización de dispositivo no permite:

• Social Connections que usan claves de desarrollador de Auth0, a menos que estés usando la experiencia de Universal Login
• Acceder a parámetros de la cadena de consulta desde la página de inicio de sesión alojada, Rules o Actions
• vinculación de cuentas de usuario

Admitimos el Draft 15 completo, excepto clientes confidenciales. Para obtener más información, consulta OAuth 2.0 Device Authorization Grant Draft 15 en ietf.org.

​

Más información

• Marco de autorización de OAuth 2.0
• Protocolo OpenID Connect
• Tokens
• Logs