Plateforme d’identités Microsoft et flux d’octroi d’autorisation d’appareil OAuth 2.0

La plateforme d’identités Microsoft prend en charge l’octroi d’autorisation d’appareil, qui permet aux utilisateurs de se connecter à des appareils limités en entrée tels qu’une télévision intelligente, un appareil IoT ou une imprimante. Pour activer ce flux, l’appareil dispose que l’utilisateur visite une page web dans un navigateur sur un autre appareil pour se connecter. Une fois que l’utilisateur s’est connecté, l’appareil peut recevoir des jetons d’accès et des jetons d’actualisation en fonction des besoins.

Cet article explique comment programmer directement contre le protocole dans votre application. Dans la mesure du possible, nous vous recommandons d’utiliser les bibliothèques d’authentification Microsoft (MSAL) prises en charge au lieu d’acquérir des jetons et d’appeler des API web sécurisées. Vous pouvez faire référence à des exemples d’applications qui utilisent MSAL pour obtenir des exemples.

Diagramme de protocole

L’ensemble du flux de code de l’appareil est illustré dans le diagramme suivant. Chaque étape est expliquée dans cet article.

Requête d’autorisation de l’appareil

Le client doit d’abord vérifier auprès du serveur d’authentification un appareil et du code utilisateur utilisé pour lancer l’authentification. Le client collecte cette requête à partir du point de terminaison /devicecode. Dans la demande, le client doit également inclure les autorisations dont il a besoin pour acquérir auprès de l’utilisateur.

À partir du moment où la demande est envoyée, l’utilisateur a 15 minutes pour se connecter. Il s’agit de la valeur par défaut de expires_in. La demande ne doit être effectuée que lorsque l’utilisateur indique qu’il est prêt à se connecter.

// 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

Paramètre	Condition	Description
tenant	Obligatoire	Peut être /common, /consumers ou /organizations. Il peut également s’agir du locataire d’annuaire à partir duquel vous souhaitez demander l’autorisation au format GUID ou convivial.
client_id	Obligatoire	L’ID d’application (client) que l’expérience Inscriptions d’applications du centre d’administration Microsoft Entra a attribué à votre application.
scope	Obligatoire	Liste séparée par des espaces d’ étendues pour lesquelles vous souhaitez que l’utilisateur donne son consentement.

Réponse d’autorisation d’appareil

Une réponse positive est un objet JSON contenant les informations nécessaires pour permettre à l’utilisateur de se connecter.

Paramètre	Format	Description
device_code	Chaîne	Chaîne longue servant à vérifier la session entre le client et le serveur d’autorisation. Le client utilise ce paramètre pour demander le jeton d’accès au serveur d’autorisation.
user_code	Chaîne	Chaîne courte présentée à l’utilisateur utilisé pour identifier la session sur un appareil secondaire.
verification_uri	URI	L’URI auquel l’utilisateur doit accéder pour user_code se connecter.
expires_in	Int	Nombre de secondes avant l’expiration de device_code et user_code.
interval	Int	Nombre de secondes pendant lesquelles le client doit attendre entre les requêtes d’interrogation.
message	Chaîne	Chaîne compréhensible avec des instructions pour l’utilisateur. Cela peut être localisé en incluant un paramètre de requête dans la requête du formulaire ?mkt=xx-XX, en remplissant le code de culture de langue approprié.

Remarque

Le verification_uri_complete champ de réponse n’est pas inclus ou pris en charge pour l’instant. Nous le mentionnons, car si vous lisez la norme que vous voyez répertoriée verification_uri_complete comme partie facultative de la norme de flux de code de l’appareil.

Authentification de l’utilisateur

Une fois que le client reçoit et verification_urique les valeurs sont affichées user_code et que l’utilisateur est dirigé vers la connexion via son navigateur mobile ou PC.

Si l’utilisateur s’authentifie avec un compte personnel, à l’aide /common ou /consumers, il est invité à se reconnecter pour transférer l’état d’authentification vers l’appareil. Cela est dû au fait que l’appareil ne peut pas accéder aux cookies de l’utilisateur. Ils sont invités à donner leur consentement aux autorisations demandées par le client. Toutefois, cela ne s’applique pas aux comptes professionnels ou scolaires utilisés pour s’authentifier.

Pendant que l’utilisateur s’authentifie à l’adresse verification_uri, le client doit interroger le /token point de terminaison pour le jeton demandé à l’aide du 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...

Paramètre	Obligatoire	Description
tenant	Obligatoire	Le même locataire ou l’alias de locataire utilisé dans la requête initiale.
grant_type	Obligatoire	Doit être urn:ietf:params:oauth:grant-type:device_code
client_id	Obligatoire	Doit correspondre à l’utilisé client_id dans la requête initiale.
device_code	Obligatoire	Retourné device_code dans la demande d’autorisation de l’appareil.

Erreurs attendues

Le flux de code de l’appareil est un protocole d’interrogation, de sorte que les erreurs fournies au client doivent être attendues avant la fin de l’authentification utilisateur.

Erreur	Description	Action du client
authorization_pending	L’utilisateur n’a pas terminé l’authentification, mais n’a pas annulé le flux.	Répétez la requête après au moins interval secondes.
authorization_declined	L’utilisateur final a refusé la demande d’autorisation.	Arrêtez l’interrogation et revenez à un état non authentifié.
bad_verification_code	L’envoi device_code au /token point de terminaison n’a pas été reconnu.	Vérifiez que le client envoie le correct device_code dans la demande.
expired_token	La valeur de l’opération expires_in a été dépassée et l’authentification n’est plus possible avec device_code.	Arrêtez l’interrogation et revenez à un état non authentifié.

Réponse d’authentification réussie

Un jeton de réponse de réussite se présente ainsi :

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

Paramètre	Format	Description
token_type	Chaîne	A toujours la valeur Bearer.
scope	Chaînes séparées par espace	Si un jeton d’accès a été retourné, cela répertorie les étendues pour lesquelles le jeton d’accès est valide.
expires_in	Int	Nombre de secondes pendant lesquelles le jeton d’accès inclus est valide.
access_token	Chaîne opaque	Émise pour les étendues qui ont été demandées.
id_token	JWT	Émis si le paramètre scope d’origine incluait l’étendue openid.
refresh_token	Chaîne opaque	Émis si le paramètre de scope d’origine inclus offline_access.

Vous pouvez utiliser le jeton d’actualisation pour acquérir de nouveaux jetons d’accès et des jetons d’actualisation à l’aide du même flux documenté dans la documentation du flux de code OAuth.

Avertissement

N’essayez pas de valider ou de lire des jetons pour toute API que vous ne possédez pas, y compris les jetons de cet exemple, dans votre code. Les jetons pour les services Microsoft peuvent utiliser un format spécial qui ne sera pas validé en tant que JWT et peut également être chiffré pour les utilisateurs consommateurs (compte Microsoft). Bien que la lecture des jetons soit un outil de débogage et d’apprentissage utile, ne prenez pas de dépendances sur cela dans votre code ou supposez des spécificités sur les jetons qui ne sont pas pour une API que vous contrôlez.