Étendues et autorisations dans la plateforme des identités Microsoft

The Microsoft identity platform implements the OAuth 2.0 authorization protocol. OAuth 2.0 est une méthode par le biais de laquelle une application tierce peut accéder aux ressources hébergées sur le web au nom d’un utilisateur. Les ressources hébergées sur le web qui s’intègrent à la plateforme d’identités Microsoft présentent un identificateur de ressource, également appelé URI d’ID d’application.

Dans cet article, vous découvrez les étendues et les autorisations dans la plateforme d'identité.

Voici une liste de quelques exemples de ressources hébergées sur le web par Microsoft :

• Microsoft Graph : https://graph.microsoft.com
• API de messagerie Microsoft 365 : https://outlook.office.com
• Azure Key Vault : https://vault.azure.net

Il en va de même pour toutes les ressources tierces qui s’intègrent à la plateforme d’identités Microsoft. L’une de ces ressources peut également définir un ensemble d’autorisations qui divisent les fonctionnalités de cette ressource en blocs plus petits. As an example, Microsoft Graph defines permissions to do the following tasks, among others:

• Lire le calendrier d’un utilisateur
• Écrire dans le calendrier d’un utilisateur
• Envoi de messages en tant qu’utilisateur

Grâce à ces types de définitions d’autorisations, la ressource dispose d’un contrôle précis sur ses données et sur la façon dont les fonctionnalités de l’API sont exposées. Une application tierce peut demander ces autorisations à des utilisateurs et des administrateurs. Ces derniers doivent approuver la requête avant que l’application puisse accéder aux données ou agir pour le compte d’un utilisateur.

Lorsque les fonctionnalités d’une ressource sont regroupées en petits ensembles d’autorisations, des applications tierces peuvent être créées pour ne demander que les autorisations nécessaires à leur fonctionnement. Les utilisateurs et les administrateurs peuvent connaître les données auxquelles l’application peut accéder. Ils peuvent ainsi être plus confiants dans le fait que l’application ne se comporte pas de manière malveillante. Les développeurs doivent toujours respecter le principe de moindre privilège et demander uniquement les autorisations dont ils ont besoin pour faire fonctionner leurs applications.

In OAuth 2.0, these types of permission sets are called scopes. They're also often referred to as permissions. Dans la plateforme d’identités Microsoft, une autorisation est représentée sous la forme d’une valeur de chaîne. Une application demande les autorisations dont elle a besoin en spécifiant l’autorisation dans le paramètre de requête scope. La plateforme d’identités prend en charge plusieurs étendues OpenID Connect bien définies, ainsi que des autorisations basées sur les ressources (pour chaque autorisation, la valeur de celle-ci est ajoutée à l’URI de l’identificateur de la ressource ou de l’ID de l’application). Par exemple, la chaîne d’autorisation https://graph.microsoft.com/Calendars.Read est utilisée pour demander l’autorisation de lire les calendriers des utilisateurs dans Microsoft Graph.

Admin-restricted permissions

Les autorisations dans la plateforme d'identités Microsoft peuvent être définies sur administrateur restreint. Par exemple, de nombreuses autorisations Microsoft Graph à privilèges plus élevés nécessitent l’approbation de l’administrateur. Si votre application requiert des autorisations restreintes aux administrateurs, l’administrateur d’une organisation doit donner son consentement à ces étendues pour le compte des utilisateurs de l’organisation. La section suivante fournit des exemples de ces types d’autorisations :

• User.Read.All : Lire les profils complets de tous les utilisateurs
• Directory.ReadWrite.All : Écrire des données dans l’annuaire d’une organisation
• Groups.Read.All : Lire tous les groupes dans le répertoire d’une organisation

Si un utilisateur consommateur peut accorder à une application l’accès à ce type de données, les utilisateurs de l’organisation ne peuvent pas accorder l’accès au même jeu de données d’entreprise sensibles. Si votre application requiert l’accès à l’une de ces autorisations d’un utilisateur de l’organisation, ce dernier recevra un message d’erreur indiquant qu’il n’est pas autorisé à donner son consentement pour les permissions de votre application.

Si l’application demande des autorisations d’application et qu’un administrateur octroie ces permissions, cet octroi n’est pas effectué pour le compte d’un utilisateur spécifique. Instead, the client application is granted permissions directly. Ces types d’autorisations sont uniquement utilisés par les services démon et d’autres applications non interactives qui s’exécutent en arrière-plan. Pour plus d’informations sur le scénario d’accès direct, consultez Scénarios d’accès dans la plateforme d'identités Microsoft.

Pour obtenir un guide pas à pas sur l’exposition des étendues dans une API web, consultez Configurer une application pour exposer une API web.

Étendues OpenId Connect

L’implémentation d’OpenID Connect sur la plateforme d’identités Microsoft comprend quelques étendues bien définies qui sont également hébergées sur Microsoft Graph : openid, email, profile et offline_access. Les étendues OpenID Connect address et phone ne sont pas prises en charge. Ces étendues sont parfois facultatives et prises en compte pour enrichir les jetons d’ID. Ces étendues n’apparaissent pas toujours sur des lignes distinctes dans la fenêtre d’invite de consentement présentée à un utilisateur.

If you request the OpenID Connect scopes and a token, you get a token to call the UserInfo endpoint.

L’étendue openid

If an app signs in by using OpenID Connect, it must request the openid scope. L’étendue openid s’affiche sur la page de consentement du compte professionnel en tant qu’autorisation de connexion.

Une application utilise cette autorisation pour recevoir un identificateur unique pour l’utilisateur sous la forme de la revendication sub. L’autorisation permet également à l’application d’accéder au point de terminaison UserInfo. L’étendue openid peut être utilisée sur le point de terminaison des jetons de la plateforme d’identités Microsoft pour acquérir des jetons d’ID. L’application peut utiliser ces derniers pour l’authentification.

L’étendue email

L’étendue email peut être utilisée avec l’étendue openid et toute autre étendue. Elle permet à l’application d’accéder à l’adresse de messagerie principale de l’utilisateur sous la forme de la revendication email.

La revendication email est incluse dans un jeton uniquement si une adresse e-mail est associée au compte d’utilisateur, ce qui n’est pas toujours le cas. Si votre application utilise l’étendue email, l’application doit être en mesure de traiter un cas dans lequel aucune revendication email n’existe dans le jeton.

L’étendue profile

L’étendue profile peut être utilisée avec l’étendue openid et toute autre étendue. Elle permet à l’application d’accéder à une grande quantité d’informations sur l’utilisateur, notamment, sans s’y limiter, le prénom de l’utilisateur, son nom de famille, son nom d’utilisateur privilégié et l’ID d’objet.

Pour obtenir la liste complète des revendications profile disponibles dans le paramètre id_tokens pour un utilisateur donné, consultez la id_tokensréférence.

L’étendue offline_access

L’étendue offline_access permet à votre application d’accéder aux ressources pour le compte de l’utilisateur pendant une période prolongée. Dans la page de consentement, cette étendue apparaît comme l’autorisation Conserver l’accès aux données auxquelles vous lui avez donné l’accès.

Si une autorisation déléguée est accordée, offline_access est implicitement accordée. Vous pouvez supposer que l’application a offline_access s’il existe des autorisations déléguées accordées. Les jetons d’actualisation sont de longue durée. Votre application peut obtenir de nouveaux jetons d’accès lorsque les plus anciens arrivent à expiration.

Sur la plateforme d’identités Microsoft (requêtes adressées au point de terminaison v2.0), votre application doit demander explicitement l’étendue offline_access pour recevoir les jetons d’actualisation. Par conséquent, lorsque vous échangez un code d’autorisation dans leflux de code d’autorisation OAuth 2.0, vous recevez un jeton d’accès à partir du point de terminaison /token.

Le jeton d’accès est valide pendant environ une heure. À ce stade, votre application doit rediriger l’utilisateur vers le point de terminaison /authorize afin de demander un nouveau code d’autorisation. Pendant ce réacheminement et en fonction du type d’application, l’utilisateur peut devoir entrer à nouveau ses informations d’identification ou accepter une nouvelle fois les autorisations.

Le jeton d’actualisation a une expiration plus longue que le jeton d’accès et est généralement valide pendant 90 jours. Pour en savoir plus sur la récupération et l’utilisation des jetons d’actualisation, consultez la page Référence sur le protocole de la plateforme d’identités Microsoft.

L’inclusion du jeton d’actualisation dans la réponse peut dépendre de plusieurs facteurs, notamment de la configuration spécifique de votre application et des étendues demandées pendant le processus d’autorisation. Si vous vous attendez à recevoir un jeton d’actualisation dans la réponse, mais que ce n’est pas le cas, tenez compte des facteurs suivants :

• Scope requirements: Ensure that you're requesting the offline_access scopes along with any other necessary scopes.
• type d’octroi d’autorisation: le jeton d’actualisation est fourni lors de l’utilisation du type d’octroi par code d’autorisation. Si votre flux diffère, la réponse peut être affectée.
• Client configuration: Check your application's settings in the identity platform. Certaines configurations peuvent restreindre l’émission de jetons d’actualisation.

L’étendue .default

L’étendue .default est utilisée pour faire référence de manière générique à un service de ressource (API) dans une requête, sans identifier d’autorisations spécifiques. Si le consentement est nécessaire, l’utilisation de .default signale que le consentement doit être demandé pour toutes les autorisations requises répertoriées dans l’inscription de l’application (pour toutes les API de la liste).

La valeur du paramètre d’étendue est construite à l’aide de l’URI d’identificateur pour la ressource et de .default, séparés par une barre oblique (/). Par exemple, si l’URI de l’identificateur de la ressource est https://contoso.com, l’étendue à demander est https://contoso.com/.default. Pour savoir quand vous devez inclure une deuxième barre oblique afin de correctement demander le jeton, consultez la section relative aux barres obliques de fin.

L’utilisation de scope={resource-identifier}/.default est fonctionnellement identique à celle de resource={resource-identifier} sur le point de terminaison v1.0 (où {resource-identifier} est l’URI de l’identificateur pour l’API, par exemple https://graph.microsoft.com pour Microsoft Graph).

The .default scope can be used in any OAuth 2.0 flow and to initiate admin consent. Its use is required in the On-Behalf-Of flow and client credentials flow.

Les clients ne peuvent pas combiner le consentement statique (.default) et le consentement dynamique dans une seule demande. Ainsi, scope=https://graph.microsoft.com/.default Mail.Read génère une erreur, car il combine des types d’étendue différents.

.default lorsque l’utilisateur donne son consentement

Le paramètre d’étendue .default déclenche uniquement une invite de consentement si le consentement n’a pas été accordé pour une autorisation déléguée entre le client et la ressource, au nom de l’utilisateur connecté.

Si le consentement existe, le jeton retourné contient toutes les étendues octroyées pour cette ressource pour l’utilisateur connecté. Toutefois, si aucune autorisation n’a été accordée pour la ressource demandée (ou si le paramètre prompt=consent est fourni), une invite de consentement s’affiche pour toutes les autorisations requises configurées sur l’inscription de l’application cliente, pour toutes les API de la liste.

Par exemple, si l’étendue https://graph.microsoft.com/.default est demandée, votre application demande un jeton d’accès pour l’API Microsoft Graph. Si au moins une autorisation déléguée a été accordée pour Microsoft Graph pour le compte de l’utilisateur connecté, la connexion se poursuit. Toutes les autorisations déléguées Microsoft Graph qui ont été accordées pour cet utilisateur seront incluses dans le jeton d’accès. Si aucune autorisation n’a été accordée pour la ressource demandée (Microsoft Graph, dans cet exemple), une invite de consentement est présentée pour toutes les autorisations requises configurées sur l’application, pour toutes les API de la liste.

Exemple 1 : L’utilisateur, ou l’administrateur de locataire, a accordé des autorisations

Dans cet exemple, l’utilisateur ou un administrateur de locataire a accordé au client les autorisations Microsoft Graph Mail.Read et User.Read.

Si le client demande scope=https://graph.microsoft.com/.default, aucune invite de consentement ne s’affiche, quel que soit le contenu des autorisations inscrites par l’application cliente pour Microsoft Graph. Le jeton retourné contient les étendues Mail.Read et User.Read.

Exemple 2 : L’utilisateur n’a pas accordé d’autorisations entre le client et la ressource

Dans cet exemple, l’utilisateur n’a pas donné son consentement entre le client et Microsoft Graph, pas plus qu’un administrateur. Le client s’est inscrit aux autorisations User.Read et Contacts.Read ainsi qu’à l’étendue Azure Key Vault https://vault.azure.net/user_impersonation.

Lorsque le client demande un jeton pour scope=https://graph.microsoft.com/.default, l’utilisateur voit une page de consentement pour les étendues Microsoft Graph User.Read et Contacts.Read, et pour l’étendue de la Azure Key Vault user_impersonation. Le jeton retourné contient uniquement les étendues User.Read et Contacts.Read, et il peut être utilisé uniquement pour Microsoft Graph.

Exemple 3 : L’utilisateur a donné son consentement, et le client demande des étendues supplémentaires

Dans cet exemple, l’utilisateur a déjà donné son consentement à Mail.Read pour le client. Le client s’est inscrit pour l’étendue Contacts.Read.

Le client effectue d’abord une connexion avec scope=https://graph.microsoft.com/.default. En fonction du paramètre scopes de la réponse, le code de l’application détecte que seul Mail.Read a été accordé. Le client lance alors une deuxième connexion à l’aide de scope=https://graph.microsoft.com/.default, et cette fois force le consentement à l’aide de prompt=consent. Si l’utilisateur est autorisé à donner son consentement pour toutes les autorisations enregistrées par l’application, il affiche l’invite de consentement. (Si ce n'est pas le cas, on leur montre un message d'erreur ou le formulaire de demande de consentement de l'administrateur .) Tant Contacts.Read que Mail.Read figurent dans l'invite de consentement. Si le consentement est accordé et que la connexion se poursuit, le jeton retourné est destiné à Microsoft Graph et contient Mail.Read et Contacts.Read.

Utilisation de l’étendue .default avec le client

Dans certains cas, un client peut demander sa propre étendue .default. L’exemple suivant illustre ce cas de figure.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Cet exemple de code produit une page de consentement pour toutes les autorisations inscrites si les descriptions précédentes du consentement et .default s’appliquent au scénario. Ensuite, le code retourne un id_token, plutôt qu’un jeton d’accès.

Les nouveaux clients ciblant la plateforme d’identités Microsoft ne doivent pas utiliser cette configuration. Assurez-vous de migrer vers la bibliothèque Microsoft Authentication Library (MSAL) à partir de la bibliothèque Azure AD Authentication Library (ADAL).

Flux d’octroi des informations d’identification du client et .default

Another use of .default is to request app roles (also known as application permissions) in a non-interactive application like a daemon app that uses the client credentials grant flow to call a web API.

Pour définir des rôles d’application (autorisations d’application) pour une API web, consultez Ajouter des rôles d’application dans votre application.

Client credentials requests in your client service must include scope={resource}/.default. Ici, {resource} est l’API web que votre application envisage d’appeler et pour laquelle elle souhaite obtenir un jeton d’accès. Issuing a client credentials request by using individual application permissions (roles) is not supported. Toutes les autorisations d’application (rôles) qui ont été accordées pour cette API web sont incluses dans le jeton d’accès retourné.

Pour accorder l’accès aux rôles que vous définissez, y compris l’octroi du consentement administrateur pour l’application, consultez Configurer une application cliente pour accéder à une API web.

Barre oblique de fin et .default

Certains URI de ressource ont une barre oblique de fin, par exemple, https://contoso.com/ par opposition à https://contoso.com. La barre oblique de fin peut entraîner des problèmes de validation des jetons. Les problèmes se produisent principalement lorsqu’un jeton est demandé pour Azure Resource Manager (https://management.azure.com/).

Dans ce cas, une barre oblique à la fin de l’URI de ressource signifie que la barre oblique doit être présente lorsque le jeton est demandé. Ainsi, lorsque vous demandez un jeton pour https://management.azure.com/ et que vous utilisez .default, vous devez demander https://management.azure.com//.default (prenez note de la double barre oblique).

En général, si vous vérifiez que le jeton est émis et que celui-ci est rejeté par l’API qui doit l’accepter, ajoutez une deuxième barre oblique, puis réessayez.

See also

• Demande d’autorisations par le biais d’un consentement dans la plateforme d’identités
• Jetons d’ID de la plateforme d’identités Microsoft
• Jetons d’accès de la plateforme d’identités Microsoft