Flujo de concesión de autorización de dispositivo de OAuth 2.0 y la Plataforma de identidad de Microsoft

La Plataforma de identidad de Microsoft admite la concesión de autorización de dispositivo, lo que permite que los usuarios inicien sesión en dispositivos con limitaciones de entrada, como un televisor inteligente, un dispositivo IoT o una impresora. Para habilitar este flujo, el dispositivo requiere que el usuario visite una página web en un explorador en otro dispositivo para iniciar sesión. Una vez que el usuario inicia sesión, el dispositivo es capaz de obtener tokens de acceso y tokens de actualización según sea necesario.

En este artículo se describe cómo programar directamente con el protocolo de la aplicación. Cuando sea posible, se recomienda usar las bibliotecas de autenticación de Microsoft (MSAL) admitidas, en lugar de adquirir tokens y API web protegidas por llamadas. Para obtener ejemplos, consulte las aplicaciones de ejemplo que usan MSAL.

Diagrama de protocolo

Todo el flujo de código del dispositivo se muestra en el diagrama siguiente. Cada uno de los pasos se explica en este artículo.

Solicitud de autorización de dispositivo

El cliente debe primero realizar una comprobación con el servidor de autenticación para obtener un código de usuario y dispositivo, utilizados para iniciar la autenticación. El cliente recopila esta solicitud desde el punto de conexión /devicecode. En la solicitud, el cliente también debe incluir los permisos que necesita obtener por parte del usuario.

Desde el momento en que se envía la solicitud, el usuario tiene 15 minutos para iniciar sesión. Este es el valor predeterminado de la clase expires_in. La solicitud solo se debe realizar cuando el usuario indique que está listo para iniciar sesión.

// Line breaks are for legibility only.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/devicecode
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile

Parámetro	Condition	Descripción
tenant	Requerido	Puede ser /common, /consumers o /organizations. También puede ser el inquilino de directorio al que desea solicitar permiso en el formato de nombre descriptivo o GUID.
client_id	Obligatorio	El identificador de aplicación (cliente) que elcentro de administración de Microsoft Entra: experiencia de registro de aplicaciones asignó a la aplicación.
scope	Obligatorio	Una lista separada por espacios de ámbitos que desea que el usuario consienta.

Respuesta de autorización de dispositivo

Una respuesta correcta es un objeto JSON que contenga la información necesaria para permitir que el usuario inicie sesión.

Parámetro	Formato	Descripción
device_code	String	Cadena larga que se usa para comprobar la sesión entre el cliente y el servidor de autorización. El cliente usa este parámetro para solicitar el token de acceso al servidor de autorización.
user_code	Cadena	Cadena corta que se muestra al usuario y se usa para identificar la sesión en un dispositivo secundario.
verification_uri	URI	Identificador URI al que debe ir el usuario con el user_code para iniciar sesión.
expires_in	int	Número de segundos antes de que device_code y user_code expiren.
interval	int	Número de segundos que el cliente debe esperar entre solicitudes de sondeo.
message	String	Cadena legible con instrucciones para el usuario. Esto se puede traducir mediante la inclusión de un parámetro de consulta en la solicitud del formulario ?mkt=xx-XX, con el código de referencia cultural del idioma correspondiente.

Nota:

El campo de respuesta verification_uri_complete no se incluye ni se admite en este momento. Lo mencionamos porque, si lee el estándar, verá que verification_uri_complete aparece como parte opcional del estándar de flujo de código del dispositivo.

Autenticación del usuario

Una vez que el cliente recibe user_code y verification_uri, se muestran los valores y el usuario se dirige a iniciar sesión a través de su navegador móvil o PC.

Si el usuario se autentica con una cuenta personal con /common o /consumers, se le pedirá que vuelva a iniciar sesión para transferir el estado de autenticación al dispositivo. Esto se debe a que el dispositivo no puede acceder a las cookies del usuario. También se le pedirá que dé su consentimiento a los permisos que solicita el cliente. Sin embargo, esto no se aplica a las cuentas profesionales o educativas que se usan para la autenticación.

Mientras el usuario se autentica en verification_uri, el cliente debe sondear el punto de conexión /token para obtener el token solicitado mediante el uso de device_code.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=00001111-aaaa-2222-bbbb-3333cccc4444&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...

Parámetro	Obligatorio	Descripción
tenant	Obligatorio	El mismo inquilino o alias de inquilino usado en la solicitud inicial.
grant_type	Obligatorio	Debe ser urn:ietf:params:oauth:grant-type:device_code
client_id	Obligatorio	Debe coincidir con el valor de client_id utilizado en la solicitud inicial.
device_code	Obligatorio	Valor de device_code devuelto en la solicitud de autorización de dispositivo.

Errores esperados

El flujo de código del dispositivo es un protocolo de sondeo, por lo que los errores que se proporcionan al cliente deben esperarse antes de completar la autenticación del usuario.

Error	Descripción	Acción del cliente
authorization_pending	El usuario no ha finalizado la autenticación, pero canceló el flujo.	Repetir la solicitud después de, por lo menos, los segundos especificados en interval.
authorization_declined	El usuario final ha denegado la solicitud de autorización.	Detener el sondeo y revertir a un estado de no autenticado.
bad_verification_code	No se reconoció el valor de device_code que se envió al punto de conexión /token.	Comprobar que el cliente está enviando el valor correcto de device_code en la solicitud.
expired_token	El valor de expires_in se ha superado y la autenticación ya no es posible con device_code.	Detener el sondeo y revertir a un estado de no autenticado.

Respuesta de autenticación correcta

Una respuesta correcta del token tiene el siguiente aspecto:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parámetro	Formato	Descripción
token_type	String	Siempre es Bearer.
scope	Cadenas separadas por espacios	Si se devolvió un token de acceso, esto muestra los ámbitos en los que es válido el token de acceso.
expires_in	int	Número de segundos durante los que el token de acceso incluido es válido.
access_token	Cadena opaca	Se emite para los ámbitos solicitados.
id_token	JWT	Se emite si el parámetro scope original incluye el ámbito openid.
refresh_token	Cadena opaca	Se emite si el parámetro scope original incluye offline_access.

Puede usar el token de actualización para adquirir nuevos tokens de acceso y tokens de actualización con el mismo flujo que se indica en la documentación del flujo de código de OAuth.

Advertencia

No intente validar ni leer tokens para ninguna API de su propiedad, incluidos los tokens de este ejemplo, en el código. Los tokens de los servicios de Microsoft pueden usar un formato especial que no se validará como un JWT y también se pueden cifrar para los usuarios consumidores (cuenta Microsoft). Aunque la lectura de tokens es una herramienta útil de depuración y aprendizaje, no tome dependencias de esto en el código ni asuma detalles sobre los tokens que no son para una API que controle.