Plataforma de identidad de Microsoft y flujo de concesión de autorización de dispositivos de OAuth 2.0

La plataforma de identidad de Microsoft admite la concesión de autorización de dispositivos, que permite a los usuarios iniciar sesión en dispositivos con restricciones de entrada, como un televisor inteligente, un dispositivo IoT o una impresora. Para habilitar este flujo, el dispositivo tiene al usuario que visita una página web en un explorador en otro dispositivo para iniciar sesión. Una vez que el usuario inicia sesión, el dispositivo puede obtener tokens de acceso y actualizar los tokens según sea necesario.

En este artículo se describe cómo programar directamente contra el protocolo en su 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. Puede consultar aplicaciones de ejemplo que usan MSAL para obtener ejemplos.

Diagrama de protocolo

El flujo de código de dispositivo completo se muestra en el diagrama siguiente. Cada paso se explica en este artículo.

Solicitud de autorización del dispositivo

El cliente debe comprobar primero con el servidor de autenticación de un dispositivo y código de usuario que se usa para iniciar la autenticación. El cliente recopila esta solicitud del /devicecode punto de conexión. En la solicitud, el cliente también debe incluir los permisos que necesita adquirir 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 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	Condición	Descripción
tenant	Obligatorio	Puede ser /common, /consumers o /organizations. También puede ser el inquilino de directorio desde el que desea solicitar permiso en el FORMATO GUID o nombre descriptivo.
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 del dispositivo

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

Parámetro	Formato	Descripción
device_code	Cuerda	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 desde el servidor de autorización.
user_code	Cuerda	Cadena corta que se muestra al usuario que se usa para identificar la sesión en un dispositivo secundario.
verification_uri	URI	El URI al que el usuario debe ir 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	Cuerda	Una cadena legible con instrucciones para el usuario. Esto se puede localizar mediante la inclusión de un parámetro de consulta en la solicitud del formulario ?mkt=xx-XX, rellenando el código de referencia cultural de idioma adecuado.

Nota:

El verification_uri_complete campo de respuesta no se incluye ni admite en este momento. Mencionamos esto porque si lee el estándar , verá que verification_uri_complete aparece como una 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, mediante /common o /consumers, se le pide 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. Se les pide que consienten los permisos solicitados por el cliente. Sin embargo, esto no se aplica a las cuentas profesionales o educativas que se usan para autenticarse.

Mientras el usuario se autentica en verification_uri, el cliente debe sondear el punto de conexión del /token token solicitado mediante 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 alias de inquilino o 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 client_id usado en la solicitud inicial.
device_code	Obligatorio	device_code devuelto en la solicitud de autorización del dispositivo.

Errores esperados

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

Error	Descripción	Acción del cliente
authorization_pending	El usuario no ha terminado de autenticarse, pero no ha cancelado el flujo.	Repita la solicitud después de al menos interval segundos.
authorization_declined	El usuario final denegó la solicitud de autorización.	Detenga el sondeo y vuelva a un estado no autenticado.
bad_verification_code	No device_code se reconoció el objeto enviado al /token punto de conexión.	Compruebe que el cliente envía el valor correcto 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.	Detenga el sondeo y vuelva a un estado no autenticado.

Respuesta de autenticación exitosa

Una respuesta de token correcta es similar a la siguiente:

{
    "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	Cuerda	Siempre Bearer.
scope	Cadenas separadas por espacios	Si se devolvió un token de acceso, se enumeran los ámbitos en los que el token de acceso es válido.
expires_in	Int	Número de segundos en 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 incluía el ámbito de openid.
refresh_token	Cadena opaca	Se emite si el parámetro scope original incluía offline_access.

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

Advertencia

No intente validar ni leer tokens para ninguna API que no posea, 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 JWT y, además, se pueden cifrar para los usuarios consumidores (cuenta Microsoft). Aunque leer tokens es una herramienta útil de depuración y aprendizaje, no dependa de esto en su código ni asuma especificaciones sobre los tokens que no son para una API que usted controla.