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

Article
04/08/2024

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.

Device code flow

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.

Partager via