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:
- El dispositivo envía una solicitud al endpoint
/api/oauth/device/codecon suclient_idy elscopesolicitado - Auris devuelve un
device_code(opaco, largo), unuser_code(corto, legible, 8 caracteres), unaverification_uriy unintervalde sondeo - El dispositivo muestra el
user_codey laverification_urial usuario - El usuario visita la URL de verificación en un navegador, introduce el código y se autentica con Auris
- Mientras tanto, el dispositivo consulta
POST /api/auth/tokencongrant_type=urn:ietf:params:oauth:grant-type:device_codeal intervalo especificado - Una vez que el usuario aprueba, el siguiente sondeo devuelve un access token y un refresh token
- 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:
| Ajuste | Predeterminado | Notas |
|---|---|---|
| Duración del código | 600 segundos (10 minutos) | Tiempo máximo que tiene el usuario para introducir el código y aprobarlo |
| Intervalo de sondeo | 5 segundos | Intervalo mínimo entre solicitudes de sondeo de token desde el dispositivo |
| Longitud del código de usuario | 8 caracteres | Alfanumé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
JavaScript SDK
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:
| Campo | Tipo | Descripción |
|---|---|---|
device_code | string | Código opaco usado por el dispositivo para sondear el token. Mantener en secreto. |
user_code | string | Código alfanumérico corto (8 caracteres) que se muestra al usuario. |
verification_uri | string | URL que el usuario visita para introducir el código. |
verification_uri_complete | string | URL con el código pre-rellenado como parámetro de consulta. |
expires_in | number | Segundos hasta que expira el código del dispositivo (predeterminado: 600). |
interval | number | Intervalo 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 error | Estado HTTP | Significado | Acción del cliente |
|---|---|---|---|
authorization_pending | 400 | El usuario aún no ha aprobado la solicitud | Continuar sondeando al intervalo especificado |
slow_down | 428 | Sondeo demasiado frecuente | Aumentar el intervalo de sondeo en 5 segundos |
expired_token | 400 | El código del dispositivo ha expirado | Reiniciar el flujo desde el paso 1 |
access_denied | 400 | El usuario rechazó explícitamente la solicitud | Mostrar 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:
- Solicita al usuario que introduzca el código de 8 caracteres
- Autentica al usuario (inicio de sesión requerido si no hay sesión activa)
- Muestra el nombre de la aplicación solicitante y los scopes solicitados
- Pide al usuario que apruebe o rechace la solicitud
- 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
/api/oauth/device/codeSolicita 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.
/api/auth/tokenEndpoint 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.
/api/oauth/device/verifyPágina de verificación alojada. Acepta el parámetro de consulta opcional user_code para pre-rellenar.
/api/oauth/device/codesRequires: manage:device_codesLista los códigos de dispositivo activos para el tenant. Endpoint de administración para monitorización y depuración.
Permisos Necesarios
| Operación | Permiso |
|---|---|
| Habilitar Flujo de Dispositivo en una aplicación | manage:applications |
| Listar códigos de dispositivo activos | manage:device_codes |
| Revocar un código de dispositivo | manage:device_codes |
| Solicitar/sondear para el token | Sin permiso requerido (endpoint público) |
Guías Relacionadas
- Hosted Login (PKCE) — Autenticación interactiva basada en navegador
- Credenciales M2M (Client Credentials) — Autenticación servidor a servidor sin usuario
- CIBA (Autenticación por Backchannel) — Autenticación desacoplada en un dispositivo separado