Skip to Content

Flujo de Autorización de Dispositivos

El Device Authorization Grant (RFC 8628) permite a los usuarios iniciar sesión en dispositivos que tienen capacidades de navegador limitadas o nulas. En lugar de introducir las credenciales directamente en el dispositivo, al usuario se le muestra un código corto y una URL. Visita la URL desde un teléfono o portátil, introduce el código y aprueba la solicitud. Mientras tanto, el dispositivo consulta el endpoint de tokens hasta que el usuario completa la autorización.

Casos de uso comunes:

  • Aplicaciones de Smart TV que muestran un código en pantalla para que el usuario lo apruebe desde su teléfono
  • Herramientas CLI que abren un navegador para que el usuario se autentique
  • Dispositivos IoT sin teclado ni pantalla que imprimen un código en la salida serie
  • Terminales de quiosco y punto de venta

Cómo Funciona

El flujo de dispositivo es un protocolo de dos canales. El dispositivo se comunica con el endpoint de tokens, mientras el usuario interactúa con Auris en un navegador desde un dispositivo separado:

  1. El dispositivo envía una solicitud al endpoint /api/oauth/device/code con su client_id y el scope solicitado
  2. Auris devuelve un device_code (opaco, largo), un user_code (corto, legible, 8 caracteres), una verification_uri y un interval de sondeo
  3. El dispositivo muestra el user_code y la verification_uri al usuario
  4. El usuario visita la URL de verificación en un navegador, introduce el código y se autentica con Auris
  5. Mientras tanto, el dispositivo consulta POST /api/auth/token con grant_type=urn:ietf:params:oauth:grant-type:device_code al intervalo especificado
  6. Una vez que el usuario aprueba, el siguiente sondeo devuelve un access token y un refresh token
  7. Si el usuario rechaza o el código expira, el sondeo devuelve un error

Configuración en la Consola

Habilitar el Flujo de Dispositivo

En la Consola de Auris, ve a Aplicaciones y selecciona la aplicación que usará el flujo de dispositivo. En la pestaña Configuración, activa Habilitar Flujo de Dispositivo.

Configurar los Ajustes

Establece la duración del código del dispositivo y el intervalo de sondeo:

AjustePredeterminadoNotas
Duración del código600 segundos (10 minutos)Tiempo máximo que tiene el usuario para introducir el código y aprobarlo
Intervalo de sondeo5 segundosIntervalo mínimo entre solicitudes de sondeo de token desde el dispositivo
Longitud del código de usuario8 caracteresAlfanumérico, mayúsculas, fácil de leer y escribir

Anotar el Client ID

El flujo de dispositivo usa un cliente público (sin client secret). Copia el Client ID de la pestaña Credenciales.


Implementación

import { AurisClient } from '@auris/js' const auris = new AurisClient({ domain: 'auth.tudominio.com', clientId: 'tu-client-id-de-app-dispositivo', }) // Paso 1: Solicitar un código de dispositivo const deviceAuth = await fetch('https://auth.tudominio.com/api/oauth/device/code', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ client_id: 'tu-client-id-de-app-dispositivo', scope: 'openid profile email', }), }).then(r => r.json()) // Paso 2: Mostrar al usuario console.log(`Ve a: ${deviceAuth.verification_uri}`) console.log(`Introduce el código: ${deviceAuth.user_code}`) // Paso 3: Sondear para obtener el token const token = await sondearToken(deviceAuth) async function sondearToken(deviceAuth) { const interval = deviceAuth.interval * 1000 // convertir a ms const expiresAt = Date.now() + deviceAuth.expires_in * 1000 while (Date.now() < expiresAt) { await new Promise(resolve => setTimeout(resolve, interval)) const response = await fetch('https://auth.tudominio.com/api/auth/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: deviceAuth.device_code, client_id: 'tu-client-id-de-app-dispositivo', }), }) if (response.ok) { return await response.json() } const error = await response.json() if (error.error === 'authorization_pending') { continue // el usuario aún no ha aprobado } if (error.error === 'slow_down') { await new Promise(resolve => setTimeout(resolve, 5000)) // esperar más continue } if (error.error === 'expired_token') { throw new Error('El código del dispositivo ha expirado. Por favor reinicia el flujo.') } if (error.error === 'access_denied') { throw new Error('El usuario rechazó la solicitud de autorización.') } throw new Error(`Error inesperado: ${error.error}`) } throw new Error('El código del dispositivo ha expirado.') }

Respuesta del Código de Dispositivo

Al solicitar un código de dispositivo, Auris devuelve los siguientes campos:

CampoTipoDescripción
device_codestringCódigo opaco usado por el dispositivo para sondear el token. Mantener en secreto.
user_codestringCódigo alfanumérico corto (8 caracteres) que se muestra al usuario.
verification_uristringURL que el usuario visita para introducir el código.
verification_uri_completestringURL con el código pre-rellenado como parámetro de consulta.
expires_innumberSegundos hasta que expira el código del dispositivo (predeterminado: 600).
intervalnumberIntervalo mínimo de sondeo en segundos (predeterminado: 5).

Gestión de Errores

Durante la fase de sondeo, el endpoint de tokens devuelve códigos de error específicos para indicar el estado actual:

Código de errorEstado HTTPSignificadoAcción del cliente
authorization_pending400El usuario aún no ha aprobado la solicitudContinuar sondeando al intervalo especificado
slow_down428Sondeo demasiado frecuenteAumentar el intervalo de sondeo en 5 segundos
expired_token400El código del dispositivo ha expiradoReiniciar el flujo desde el paso 1
access_denied400El usuario rechazó explícitamente la solicitudMostrar mensaje de error, no reintentar

Respeta siempre el valor de interval y el error slow_down. Los clientes que sondeen demasiado agresivamente recibirán respuestas HTTP 428 y su intervalo de sondeo será aumentado forzosamente. Las violaciones repetidas pueden resultar en la revocación del código de dispositivo.


Página de Verificación de Usuario

Auris proporciona una página de verificación alojada en /hosted/device donde los usuarios introducen su código de dispositivo. La página:

  1. Solicita al usuario que introduzca el código de 8 caracteres
  2. Autentica al usuario (inicio de sesión requerido si no hay sesión activa)
  3. Muestra el nombre de la aplicación solicitante y los scopes solicitados
  4. Pide al usuario que apruebe o rechace la solicitud
  5. Muestra un mensaje de confirmación si tiene éxito

Si se usa la URL verification_uri_complete, el campo del código está pre-rellenado, ahorrando un paso al usuario.


Consideraciones de Seguridad

  • Corta duración del código: Los códigos de dispositivo expiran tras 600 segundos por defecto. Esto limita la ventana para la interceptación del código.
  • Códigos legibles por humanos: Los códigos de usuario de 8 caracteres usan un juego de caracteres sin ambigüedad (sin confusión entre 0/O, 1/I/l).
  • Sondeo con límite de velocidad: El endpoint de tokens aplica el intervalo de sondeo. Los clientes que sondeen demasiado rápido reciben errores slow_down.
  • Sin client secret: El flujo de dispositivo usa clientes públicos porque el dispositivo no puede almacenar un secret de forma segura. Los scopes deben limitarse en consecuencia.
  • Uso único: Cada código de dispositivo solo puede aprobarse una vez. Tras la emisión exitosa del token, el código queda invalidado.

Debido a que el flujo de dispositivo usa clientes públicos, los access tokens emitidos suelen tener una duración más corta que los de flujos de cliente confidencial. Considera usar refresh tokens para mantener sesiones largas sin volver a ejecutar el flujo de dispositivo.


Endpoints de la API

POST/api/oauth/device/code

Solicita un nuevo código de dispositivo. Requiere client_id y scope opcional en el cuerpo de la solicitud. Devuelve device_code, user_code, verification_uri, expires_in e interval.

POST/api/auth/token

Endpoint de tokens. Para el flujo de dispositivo, establece grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code y client_id. Devuelve el access token si tiene éxito, o un código de error durante el sondeo.

GET/api/oauth/device/verify

Página de verificación alojada. Acepta el parámetro de consulta opcional user_code para pre-rellenar.

GET/api/oauth/device/codesRequires: manage:device_codes

Lista los códigos de dispositivo activos para el tenant. Endpoint de administración para monitorización y depuración.


Permisos Necesarios

OperaciónPermiso
Habilitar Flujo de Dispositivo en una aplicaciónmanage:applications
Listar códigos de dispositivo activosmanage:device_codes
Revocar un código de dispositivomanage:device_codes
Solicitar/sondear para el tokenSin permiso requerido (endpoint público)

Guías Relacionadas