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, ce qui permet aux utilisateurs de se connecter à des appareils à entrée limitée comme une télévision connectée, un appareil IoT ou une imprimante. Pour activer ce flux, l’appareil demande à l’utilisateur de consulter une page web dans un navigateur sur un autre appareil pour se connecter. Lorsque l’utilisateur est connecté, l’appareil peut obtenir des jetons d’accès et actualiser les jetons si nécessaire.

Cet article explique comment programmer directement par rapport au 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 également consulter des exemples d’applications utilisant MSAL.

Schéma de protocole

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

Requête d’autorisation de l’appareil

Le client doit d’abord vérifier auprès du serveur d’authentification le code de l'appareil et de l'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 d’obtenir 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 l'objet expires_in. La demande ne doit être faite 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 dont vous souhaitez demander une autorisation au format GUID ou de nom convivial.
client_id	Requis	L’ID d’application (client) que l’expérience Inscriptions d’applications du centre d’administration Microsoft Entra a attribué à votre application.
scope	Requis	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	String	Chaîne longue utilisée pour vérifier la session entre le client et le serveur d’autorisation. Ce client est utilisé par le client pour demander le jeton d’accès au serveur d’autorisation.
user_code	Chaîne	Une chaîne courte présentée à l’utilisateur, utilisée pour identifier la session sur un appareil secondaire.
verification_uri	URI	URI auquel l’utilisateur doit accéder avec le user_code pour pouvoir se connecter.
expires_in	int	Nombre de secondes avant l’expiration de device_code et user_code.
interval	int	Nombre de secondes d’attente du client entre chaque requête d’interrogation.
message	String	Chaîne lisible par l’homme contenant des instructions pour l’utilisateur. Elle peut être localisée en incluant un paramètre de requête dans la requête sous la forme ?mkt=xx-XX, en remplissant le code de langue approprié.

Notes

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

Authentification de l’utilisateur

Une fois que le client a reçu user_code et verification_uri, les valeurs sont affichées et l'utilisateur est invité à se connecter via le navigateur de son mobile ou de son navigateur PC.

Si l’utilisateur s’authentifie avec un compte personnel avec /common ou /consumers, il est invité à se reconnecter pour transférer l’état d’authentification à l’appareil. C’est parce que l’appareil ne peut pas accéder aux cookies de l’utilisateur. Il leur est demandé de consentir aux autorisations demandées par le client. Cependant, cela ne s’applique cependant pas aux comptes professionnels ou scolaires utilisés pour l’authentification.

Tandis que l’utilisateur s’authentifie auprès de verification_uri, le client doit interroger le point de terminaison /token 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	Même locataire ou alias de locataire que celui utilisé dans la demande initiale.
grant_type	Obligatoire	Doit être urn:ietf:params:oauth:grant-type:device_code
client_id	Obligatoire	Doit correspondre au client_id utilisé dans la requête initiale.
device_code	Obligatoire	device_code retourné dans la requête d’autorisation d’appareil.

Erreurs attendues

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

Error	Description	Action du client
authorization_pending	L’utilisateur n’a pas encore terminé l’authentification, mais n’a pas annulé le flux.	Répétez la requête après interval secondes minimum.
authorization_declined	L’utilisateur final a refusé la requête d’autorisation.	Arrêtez l’interrogation et revenez à un état non authentifié.
bad_verification_code	Le device_code envoyé au point de terminaison /token n’a pas été reconnu.	Vérifiez que le client envoie le device_code approprié dans la requête.
expired_token	La valeur de 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	String	Toujours Bearer.
scope	Chaînes séparées par un espace	Si un jeton d’accès est retourné, répertorie les étendues dans 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 inclut l’étendue openid.
refresh_token	Chaîne opaque	Émise si le paramètre scope d’origine inclut offline_access.

Vous pouvez utiliser le jeton d’actualisation pour acquérir de nouveaux jetons d’accès et actualiser des jetons avec le même flux détaillé décrit dans la documentation du flux de code OAuth.

Avertissement

N’essayez pas de valider ou de lire des jetons pour des API dont vous n’êtes pas propriétaire, y compris les jetons de cet exemple, dans votre code. Les jetons associés aux services Microsoft peuvent utiliser un format spécial qui n’est pas validé comme jeton JWT, et peuvent également être chiffrés pour les utilisateurs consommateurs (de comptes Microsoft). Même si la lecture des jetons est un outil utile de débogage et d’apprentissage, n’y associez pas de dépendances dans votre code ou tenez compte des spécificités des jetons qui ne correspondent pas à une API que vous contrôlez.