Skip to Content

Flujo de autorización de dispositivos

El problema: dispositivos sin teclado

El tipo de concesión más común de OAuth 2.0 — Authorization Code con PKCE — asume que el cliente puede abrir un navegador, mostrar una página de inicio de sesión y aceptar entrada de teclado del usuario. Esta suposición falla para toda una categoría de dispositivos:

DispositivoPor qué falla OAuth estándar
Smart TVsSin teclado; los teclados en pantalla son incómodos
Herramientas CLISin navegador; interfaz solo de terminal
Consolas de juegosEntrada por mando; introducir URLs y credenciales es impráctico
Dispositivos IoTSin pantalla en absoluto, o pantalla mínima
Señalización digital / quioscosEntorno bloqueado; sin navegación en browser
Dongles de streaming (Chromecast, Fire Stick)Solo control remoto; sin teclado

Estos dispositivos necesitan autenticar usuarios, pero no pueden alojar un formulario de inicio de sesión. El usuario necesita autenticarse en otro lugar — en su teléfono o laptop — y el dispositivo necesita enterarse de que la autenticación fue exitosa.

Esto es exactamente lo que resuelve el Device Authorization Grant de OAuth 2.0 (RFC 8628).

Cómo funciona el flujo de dispositivos

El Device Authorization Grant introduce un patrón de dispositivo secundario: el dispositivo cliente muestra un código corto, el usuario introduce ese código en un dispositivo con navegador (su teléfono o laptop), y el dispositivo cliente realiza polling al servidor de autorización hasta que el usuario completa la autenticación.

El flujo paso a paso

Paso 1: El cliente solicita códigos de dispositivo y usuario

POST /api/oauth/device HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
 
client_id=tv-app-client-id
&scope=openid profile email

Paso 2: El servidor devuelve los códigos

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://auth.example.com/device",
  "verification_uri_complete": "https://auth.example.com/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}
CampoDescripción
device_codeUna cadena larga y aleatoria que el cliente usa cuando realiza polling. Nunca se muestra al usuario.
user_codeUn código corto y legible que el usuario introduce en la página de verificación.
verification_uriLa URL que el usuario visita para introducir el código.
verification_uri_completeLa URL completa con el código de usuario pre-rellenado (para códigos QR).
expires_inCuánto tiempo son válidos los códigos (segundos). Predeterminado: 600 (10 minutos).
intervalIntervalo mínimo de polling en segundos. El cliente no debe realizar polling más rápido.

Paso 3: El usuario se autentica en su dispositivo secundario

El dispositivo cliente muestra el user_code y la verification_uri al usuario. El usuario abre la URL en su teléfono o laptop, introduce el user_code, inicia sesión con sus credenciales e aprueba el dispositivo.

Paso 4: El cliente realiza polling

Mientras el usuario se autentica, el cliente realiza polling al endpoint de tokens:

POST /api/auth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
 
grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS
&client_id=tv-app-client-id

Respuestas posibles durante el polling:

RespuestaSignificado
authorization_pendingEl usuario aún no ha completado la autenticación — continúa el polling
slow_downEl cliente está realizando polling demasiado rápido — aumenta el intervalo en 5 segundos
access_deniedEl usuario rechazó la solicitud — detén el polling
expired_tokenLos códigos han expirado — reinicia el flujo
Tokens emitidosLa autenticación fue exitosa

Paso 5: Recibir tokens

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "rt_7fKp2mXa9qN3vB8yR4tL1wC6jD5sE0uH",
  "id_token": "eyJhbGciOiJSUzI1NiJ9...",
  "scope": "openid profile email"
}

El CLI de Auris (@auris/cli) utiliza el Device Flow para el comando auris login. Cuando ejecutas auris login, la CLI imprime la URL y el código, y el polling ocurre automáticamente en segundo plano. Una vez que completas el inicio de sesión en tu navegador, el CLI recibe los tokens sin que tengas que hacer nada más.

Propiedades de seguridad

  • Los user_code son cortos y legibles por humanos — diseñados para introducirse manualmente, no copiarse
  • El device_code es largo y aleatorio — previene la adivinación por fuerza bruta
  • Ambos códigos expiran (10 minutos por defecto)
  • El servidor aplica el intervalo de polling para prevenir el abuso
  • MFA se aplica normalmente — si el usuario tiene TOTP configurado, debe completarlo durante la autenticación del dispositivo
Arquitectura