Autorisations et consentement dans le point de terminaison de la plateforme d’identités MicrosoftPermissions and consent in the Microsoft identity platform endpoint

  • 21 minutes de lecture

Les applications qui s’intègrent à la plateforme d’identité Microsoft suivent un modèle d’autorisation permettant aux utilisateurs et aux administrateurs de contrôler l’accès aux données.Applications that integrate with Microsoft identity platform follow an authorization model that gives users and administrators control over how data can be accessed. L’implémentation de ce modèle d’autorisation a été mise à jour sur le point de terminaison de la plateforme d’identités Microsoft et elle modifie la façon dont une application doit interagir avec la plateforme d’identités Microsoft.The implementation of the authorization model has been updated on the Microsoft identity platform endpoint, and it changes how an app must interact with the Microsoft identity platform. Cet article aborde les concepts de base de ce modèle d’autorisation, notamment les étendues, les autorisations et le consentement.This article covers the basic concepts of this authorization model, including scopes, permissions, and consent.

Étendues et autorisationsScopes and permissions

La plateforme d’identité Microsoft implémente le protocole d’autorisation OAuth 2.0.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.OAuth 2.0 is a method through which a third-party app can access web-hosted resources on behalf of a user. Les ressources hébergées sur le web qui s’intègrent à la plateforme d’identité Microsoft présentent un identificateur de ressource, également appelé URI d’ID d’application.Any web-hosted resource that integrates with the Microsoft identity platform has a resource identifier, or Application ID URI. Voici, par exemple, quelques-unes des ressources hébergées sur le Web de Microsoft :For example, some of Microsoft's web-hosted resources include:

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

Notes

Nous vous recommandons fortement d’utiliser Microsoft Graph à la place de l’API de messagerie Office 365, etc.We strongly recommend that you use Microsoft Graph instead of Office 365 Mail API, etc.

Cela s’applique également aux ressources tierces intégrées à la plateforme d’identité Microsoft.The same is true for any third-party resources that have integrated with the Microsoft identity platform. Ces ressources peuvent également définir un ensemble d’autorisations à utiliser pour diviser la fonctionnalité de cette ressource en fragments plus réduits.Any of these resources also can define a set of permissions that can be used to divide the functionality of that resource into smaller chunks. Par exemple, Microsoft Graph a défini des autorisations pour effectuer les tâches suivantes, entre autres :As an example, Microsoft Graph has defined permissions to do the following tasks, among others:

  • Lire le calendrier d’un utilisateurRead a user's calendar
  • Écrire dans le calendrier d’un utilisateurWrite to a user's calendar
  • Envoi de messages en tant qu’utilisateurSend mail as a user

En définissant ces types d’autorisations, la ressource dispose d’un contrôle précis sur ses données et sur l’exposition de la fonctionnalité d’API.By defining these types of permissions, the resource has fine-grained control over its data and how API functionality is exposed. 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.A third-party app can request these permissions from users and administrators, who must approve the request before the app can access data or act on a user's behalf. En fragmentant les fonctionnalités de la ressource en ensembles plus réduits d’autorisations, il est possible de créer des applications tierces pour qu’elles demandent uniquement les autorisations nécessaires à leur fonctionnement.By chunking the resource's functionality into smaller permission sets, third-party apps can be built to request only the specific permissions that they need to perform their function. Les utilisateurs et les administrateurs peuvent connaître avec précision les données auxquelles l’application a accès. Ainsi, ils seront moins inquiets quant à une éventuelle intention malveillante.Users and administrators can know exactly what data the app has access to, and they can be more confident that it isn't behaving with malicious intent. Les développeurs doivent toujours respecter le concept de moindre privilège et demander uniquement les autorisations dont ils ont besoin pour faire fonctionner leurs applications.Developers should always abide by the concept of least privilege, asking for only the permissions they need for their applications to function.

Dans OAuth 2.0, ces types d’autorisations sont appelés des étendues.In OAuth 2.0, these types of permissions are called scopes. Ils sont également souvent appelés autorisations.They are also often referred to as permissions. Une autorisation est représentée dans la plateforme d’identité Microsoft sous forme de valeur de chaîne.A permission is represented in the Microsoft identity platform as a string value. Toujours dans l’exemple Microsoft Graph, la valeur de chaîne pour chaque autorisation est la suivante :Continuing with the Microsoft Graph example, the string value for each permission is:

  • Lire le calendrier d’un utilisateur en utilisant Calendars.ReadRead a user's calendar by using Calendars.Read
  • Écrire dans le calendrier d’un utilisateur en utilisant Calendars.ReadWriteWrite to a user's calendar by using Calendars.ReadWrite
  • Envoi de messages en tant qu’utilisateur en utilisant Mail.SendSend mail as a user using by Mail.Send

Généralement, une application peut demander ces autorisations en spécifiant les étendues dans les demandes dirigées vers le point de terminaison d’autorisation de la plateforme d’identités Microsoft.An app most commonly requests these permissions by specifying the scopes in requests to the Microsoft identity platform authorize endpoint. Toutefois, certaines autorisations à privilèges élevés peuvent uniquement être accordées par le biais du consentement de l’administrateur. Elles sont demandées/accordées à l’aide du point de terminaison de consentement de l’administrateur.However, certain high privilege permissions can only be granted through administrator consent and requested/granted using the administrator consent endpoint. Lisez la suite pour en savoir plus.Read on to learn more.

Types d'autorisationsPermission types

La plateforme d’identité Microsoft prend en charge deux types d’autorisations : les autorisations déléguées et les autorisations d’application.Microsoft identity platform supports two types of permissions: delegated permissions and application permissions.

  • Les autorisations déléguées sont utilisées par les applications pour lesquelles un utilisateur est connecté et présent.Delegated permissions are used by apps that have a signed-in user present. Pour ces applications, l’utilisateur ou un administrateur accorde les autorisations que l’application demande. Ensuite, l’application se voit déléguer une autorisation d’agir pour le compte de l’utilisateur connecté lors des appels à une ressource cible.For these apps, either the user or an administrator consents to the permissions that the app requests, and the app is delegated permission to act as the signed-in user when making calls to the target resource. Certaines autorisations déléguées peuvent être accordées par des utilisateurs non administrateurs, mais certaines autorisations à privilèges élevés requièrent le consentement de l’administrateur.Some delegated permissions can be consented to by non-administrative users, but some higher-privileged permissions require administrator consent. Pour connaître les rôles administrateur habilités à donner leur consentement pour les autorisations déléguées, consultez Autorisations du rôle administrateur dans Azure AD.To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD.

  • Les autorisations d’application sont utilisées par les applications qui s’exécutent sans qu’un utilisateur soit connecté et présent (les applications qui s’exécutent en tant que services ou démons en arrière-plan, par exemple).Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. Les autorisations de l’application peuvent uniquement être accordées par un administrateur.Application permissions can only be consented by an administrator.

Les autorisations effectives correspondent aux autorisations accordées à votre application lorsqu’elle envoie des requêtes à une ressource cible.Effective permissions are the permissions that your app will have when making requests to the target resource. Vous devez comprendre la différence entre les autorisations déléguées, les autorisations d’application et les autorisations effectives que votre application reçoit lorsqu’elle interroge la ressource cible.It's important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to the target resource.

  • Pour les autorisations déléguées, les autorisations effectives de votre application correspondent au niveau de privilège le moins élevé entre les autorisations déléguées que l’application a reçues (par le biais d’un consentement) et les privilèges de l’utilisateur actuellement connecté.For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. Votre application ne peut jamais avoir plus de privilèges que l’utilisateur connecté.Your app can never have more privileges than the signed-in user. Au sein des organisations, les privilèges de l’utilisateur connecté peuvent être déterminés par la stratégie ou l’appartenance à un ou plusieurs rôles d’administrateur.Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. Pour connaître les rôles administrateur habilités à donner leur consentement pour les autorisations déléguées, consultez Autorisations du rôle administrateur dans Azure AD.To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD.

    Supposons que votre application ait reçu l’autorisation déléguée User.ReadWrite.All.For example, assume your app has been granted the User.ReadWrite.All delegated permission. Cette autorisation permet nominalement à votre application de lire et mettre à jour le profil de chaque utilisateur dans une organisation.This permission nominally grants your app permission to read and update the profile of every user in an organization. Si l’utilisateur connecté est un administrateur général, votre application est en mesure de mettre à jour le profil de chaque utilisateur de l’organisation.If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. Toutefois, si l’utilisateur connecté n’a pas de rôle d’administrateur, votre application peut uniquement mettre à jour le profil de l’utilisateur connecté.However, if the signed-in user isn't in an administrator role, your app will be able to update only the profile of the signed-in user. Elle ne peut pas mettre à jour les profils des autres utilisateurs de l’organisation, car l’utilisateur pour lequel elle est autorisée à agir n’a pas ces privilèges.It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.

  • Pour les autorisations d’application, les autorisations effectives de votre application correspondent au niveau complet des privilèges impliqués par l’autorisation.For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. Par exemple, une application disposant de l’autorisation d’application User.ReadWrite.All peut mettre à jour le profil de chaque utilisateur de l’organisation.For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.

Étendues OpenId ConnectOpenID Connect scopes

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 l'instance de Microsoft Graph : openid, email, profile et offline_access.The Microsoft identity platform implementation of OpenID Connect has a few well-defined scopes that are also hosted on the Microsoft Graph: openid, email, profile, and offline_access. Les étendues OpenID Connect address et phone ne sont pas prises en charge.The address and phone OpenID Connect scopes are not supported.

En demandant les étendues OIDC et un jeton, vous obtiendrez un jeton pour appeler le point de terminaison UserInfo.Requesting the OIDC scopes and a token will give you a token to call the UserInfo endpoint.

openidopenid

Si une application exécute la connexion à l’aide d’OpenID Connect, elle doit solliciter l’étendue openid.If an app performs sign-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, et sur la page de consentement du compte Microsoft personnel en tant qu’autorisation « Afficher votre profil et se connecter aux applications et aux services à l’aide de votre compte Microsoft ».The openid scope shows on the work account consent page as the "Sign you in" permission, and on the personal Microsoft account consent page as the "View your profile and connect to apps and services using your Microsoft account" permission. Avec cette autorisation, une application peut recevoir un identifiant utilisateur unique sous la forme de la revendication sub.With this permission, an app can receive a unique identifier for the user in the form of the sub claim. Elle permet également à l’application d’accéder au point de terminaison des informations utilisateur.It also gives the app access to the UserInfo endpoint. 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.The openid scope can be used at the Microsoft identity platform token endpoint to acquire ID tokens, which can be used by the app for authentication.

emailemail

L’étendue email peut être utilisée avec l’étendue openid ainsi que d’autres.The email scope can be used with the openid scope and any others. Elle permet à l’application d’accéder à l’adresse de messagerie principale de l’utilisateur sous la forme de la revendication email.It gives the app access to the user's primary email address in the form of the email claim. 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.The email claim is included in a token only if an email address is associated with the user account, which isn't always the case. Si elle utilise l’étendue email, votre application doit être préparée à faire face à l’éventualité où la revendication email n’existerait pas dans le jeton.If it uses the email scope, your app should be prepared to handle a case in which the email claim does not exist in the token.

profileprofile

L’étendue profile peut être utilisée avec l’étendue openid ainsi que d’autres.The profile scope can be used with the openid scope and any others. Elle permet à l’application d’accéder à une quantité d’informations importante sur l’utilisateur,It gives the app access to a substantial amount of information about the user. notamment le prénom de l’utilisateur, son nom de famille, son nom d’utilisateur privilégié et l’ID d’objet.The information it can access includes, but isn't limited to, the user's given name, surname, preferred username, and object ID. Pour obtenir la liste complète des revendications de profil disponibles dans le paramètre id_token pour un utilisateur donné, consultez la page de référence id_tokens.For a complete list of the profile claims available in the id_tokens parameter for a specific user, see the id_tokens reference.

offline_accessoffline_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.The offline_access scope gives your app access to resources on behalf of the user for an extended time. 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 ».On the consent page, this scope appears as the "Maintain access to data you have given it access to" permission. Lorsqu’un utilisateur approuve l’étendue offline_access, votre application peut recevoir les jetons d’actualisation du point de terminaison des jetons de la plateforme d’identités Microsoft.When a user approves the offline_access scope, your app can receive refresh tokens from the Microsoft identity platform token endpoint. Les jetons d’actualisation sont de longue durée.Refresh tokens are long-lived. Votre application peut obtenir de nouveaux jetons d’accès lorsque les plus anciens arrivent à expiration.Your app can get new access tokens as older ones expire.

Notes

Cette autorisation s’affiche sur tous les écrans de consentement du jour, même pour les flux qui ne fournissent pas de jeton d’actualisation (le flux implicite).This permission appears on all consent screens today, even for flows that don't provide a refresh token (the implicit flow). Cela permet de couvrir les scénarios dans lesquels un client peut commencer dans le cadre du flux implicite, puis passer au flux de code où un jeton d’actualisation est attendu.This is to cover scenarios where a client can begin within the implicit flow, and then move onto to the code flow where a refresh token is expected.

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.On the Microsoft identity platform (requests made to the v2.0 endpoint), your app must explicitly request the offline_access scope, to receive refresh tokens. Ainsi, lorsque vous échangez un code d’autorisation dans le flux de code d’autorisation OAuth 2.0, vous recevez uniquement un jeton d’accès du point de terminaison /token.This means that when you redeem an authorization code in the OAuth 2.0 authorization code flow, you'll receive only an access token from the /token endpoint. Le jeton d’accès est valide pendant une courte durée :The access token is valid for a short time. il arrive généralement à expiration en une heure.The access token usually expires in one hour. À ce stade, votre application doit rediriger l’utilisateur vers le point de terminaison /authorize afin de récupérer un nouveau code d’autorisation.At that point, your app needs to redirect the user back to the /authorize endpoint to get a new authorization code. Pendant ce réacheminement, en fonction du type d’application, l’utilisateur peut devoir entrer à nouveau ses informations d’identification ou accepter une nouvelle fois les autorisations.During this redirect, depending on the type of app, the user might need to enter their credentials again or consent again to permissions.

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.For more information about how to get and use refresh tokens, see the Microsoft identity platform protocol reference.

Dans une demande d’autorisation OpenID Connect ou OAuth 2.0, une application peut demander les autorisations nécessaires à l’aide du paramètre de requête scope.In an OpenID Connect or OAuth 2.0 authorization request, an app can request the permissions it needs by using the scope query parameter. Par exemple, lorsqu’un utilisateur se connecte à une application, cette dernière envoie une requête semblable à l’exemple ci-dessous (avec des sauts de ligne ajoutés pour une meilleure lisibilité) :For example, when a user signs in to an app, the app sends a request like the following example (with line breaks added for legibility):

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

Le paramètre scope correspond à une liste d’autorisations déléguées séparées par des espaces, demandées par l’application.The scope parameter is a space-separated list of delegated permissions that the app is requesting. Chaque autorisation est indiquée par l’ajout de la valeur correspondante à l’identificateur de la ressource (URI d’ID d’application).Each permission is indicated by appending the permission value to the resource's identifier (the Application ID URI). Dans l’exemple de requête, l’application nécessite l’autorisation de lecture du calendrier de l’utilisateur et d’envoi de messages au nom de l’utilisateur.In the request example, the app needs permission to read the user's calendar and send mail as the user.

Une fois que l’utilisateur a entré ses informations d’identification, le point de terminaison de la plateforme d’identités Microsoft recherche un enregistrement correspondant du consentement d’utilisateur.After the user enters their credentials, the Microsoft identity platform endpoint checks for a matching record of user consent. Si, par le passé, l’utilisateur n’a jamais accepté les autorisations demandées et qu’un administrateur n’a jamais accepté ces autorisations pour le compte de toute l’organisation, le point de terminaison de la plateforme d’identités Microsoft demande à l’utilisateur d’accorder les autorisations demandées.If the user has not consented to any of the requested permissions in the past, nor has an administrator consented to these permissions on behalf of the entire organization, the Microsoft identity platform endpoint asks the user to grant the requested permissions.

Notes

À ce stade, les autorisations offline_access (« Conserver l’accès aux données auxquelles vous lui avez donné l’accès ») et user.read (« Vous connecter et lire votre profil ») sont automatiquement incluses dans le consentement initial pour une application.At this time, the offline_access ("Maintain access to data you have given it access to") and user.read ("Sign you in and read your profile") permissions are automatically included in the initial consent to an application. Ces autorisations sont généralement requises pour la fonctionnalité d’application appropriée : offline_access fournit à l’application l’accès aux jetons d’actualisation, critiques pour les applications natives et web, tandis que user.read donne accès à la revendication sub, ce qui permet au client ou à l’application d’identifier correctement l’utilisateur au fil du temps et d’accéder aux informations utilisateur de base.These permissions are generally required for proper app functionality - offline_access gives the app access to refresh tokens, critical for native and web apps, while user.read gives access to the sub claim, allowing the client or app to correctly identify the user over time and access rudimentary user information.

Capture d’écran de consentement dans le compte professionnel

Lorsque l’utilisateur approuve la demande d’autorisation, le consentement est enregistré de manière à ce que l’utilisateur n’ait pas à le fournir à nouveau lors des connexions suivantes à l’application.When the user approves the permission request, consent is recorded and the user doesn't have to consent again on subsequent sign-ins to the application.

Souvent, lorsqu’une organisation achète une licence ou un abonnement à une application, elle souhaite configurer proactivement l’application afin que tous les membres de l’organisation puissent l’utiliser.Often, when an organization purchases a license or subscription for an application, the organization wants to proactively set up the application for use by all members of the organization. Dans le cadre de cette procédure, un administrateur peut autoriser l’application à agir au nom de n’importe quel utilisateur au sein du locataire.As part of this process, an administrator can grant consent for the application to act on behalf of any user in the tenant. Si l’administrateur donne son consentement pour l’intégralité du locataire, les utilisateurs de l’organisation ne voient pas de page de consentement pour l’application.If the admin grants consent for the entire tenant, the organization's users won't see a consent page for the application.

Pour demander le consentement pour les autorisations déléguées pour tous les utilisateurs d’un locataire, votre application peut utiliser le point de terminaison de consentement de l’administrateur.To request consent for delegated permissions for all users in a tenant, your app can use the admin consent endpoint.

En outre, les applications doivent utiliser le point de terminaison de consentement de l’administrateur pour demander les autorisations d’application.Additionally, applications must use the admin consent endpoint to request Application Permissions.

Autorisations restreintes aux administrateursAdmin-restricted permissions

Certaines autorisations à privilège élevé de l’écosystème Microsoft peuvent être définies sur restreintes aux administrateurs.Some high-privilege permissions in the Microsoft ecosystem can be set to admin-restricted. Ces types d’autorisations peuvent être illustrés par ces exemples :Examples of these kinds of permissions include the following:

  • Lire les profils complets de tous les utilisateurs à l’aide de User.Read.AllRead all user's full profiles by using User.Read.All
  • Écrire des données dans le répertoire d’une organisation à l’aide de Directory.ReadWrite.AllWrite data to an organization's directory by using Directory.ReadWrite.All
  • Lire tous les groupes dans le répertoire d’une organisation à l’aide de Groups.Read.AllRead all groups in an organization's directory by using Groups.Read.All

Si un utilisateur consommateur peut accorder à une application l’accès à ce type de données, les utilisateurs d’organisation sont limités lorsqu’il s’agit d’octroyer l’accès au même jeu de données d’entreprise sensibles.Although a consumer user might grant an application access to this kind of data, organizational users are restricted from granting access to the same set of sensitive company data. 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.If your application requests access to one of these permissions from an organizational user, the user receives an error message that says they're not authorized to consent to your app's permissions.

Si votre application requiert l’accès aux étendues restreintes aux administrateurs pour les organisations, vous devez demander l’autorisation directement à un administrateur d’entreprise également à l’aide du point de terminaison de consentement de l’administrateur, décrit ci-dessous.If your app requires access to admin-restricted scopes for organizations, you should request them directly from a company administrator, also by using the admin consent endpoint, described next.

Si l’application demande des autorisations déléguées à privilèges élevés et qu’un administrateur accorde ces autorisations via le point de terminaison de consentement de l’administrateur, le consentement est accordé à tous les utilisateurs du locataire.If the application is requesting high privilege delegated permissions and an administrator grants these permissions via the admin consent endpoint, consent is granted for all users in the tenant.

Si l’application demande des permissions d’application et qu’un administrateur accorde ces autorisations via le point de terminaison de consentement administrateur, cette attribution n’est pas effectuée pour le compte d’un utilisateur spécifique.If the application is requesting application permissions and an administrator grants these permissions via the admin consent endpoint, this grant isn't done on behalf of any specific user. L’application cliente reçoit les autorisations directement.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.These types of permissions are only used by daemon services and other non-interactive applications that run in the background.

Notes

Veuillez noter qu’après avoir accordé le consentement administrateur à l’aide du point de terminaison de consentement administrateur, vous avez terminé d’accorder le consentement administrateur et les utilisateurs n’ont pas besoin d’effectuer d’actions supplémentaires.Please note after granting admin consent using the admin consent endpoint, you have finished granting admin consent and users do not need to perform any further additional actions. Après avoir accordé le consentement administrateur, les utilisateurs peuvent obtenir un jeton d’accès grâce au flux d’authentification standard. Le jeton d’accès en question aura toutes les autorisations nécessaires.After granting admin consent, users can get an access token via a typical auth flow and the resulting access token will have the consented permissions.

Lorsqu’un administrateur d’entreprise utilise votre application et qu’il est dirigé vers le point de terminaison d’autorisation, la plateforme d’identité Microsoft détecte le rôle de l’utilisateur et lui demande s’il souhaite donner son consentement pour le compte de l’intégralité du locataire pour les autorisations que vous avez demandées.When a Company Administrator uses your application and is directed to the authorize endpoint, Microsoft identity platform will detect the user's role and ask them if they would like to consent on behalf of the entire tenant for the permissions you have requested. Toutefois, il existe également un point de terminaison de consentement de l’administrateur dédié que vous pouvez utiliser si vous souhaitez demander proactivement qu’un administrateur accorde son autorisation pour le compte de l’intégralité du locataire.However, there is also a dedicated admin consent endpoint you can use if you would like to proactively request that an administrator grants permission on behalf of the entire tenant. Vous devez également utiliser ce point de terminaison pour demander des permissions d’application (qui ne peuvent pas être demandées à l’aide du point de terminaison d’autorisation).Using this endpoint is also necessary for requesting Application Permissions (which can't be requested using the authorize endpoint).

Si vous suivez ces étapes, votre application peut demander des autorisations pour tous les utilisateurs d’un locataire, notamment les étendues restreintes aux administrateurs.If you follow these steps, your app can request permissions for all users in a tenant, including admin-restricted scopes. Il s’agit d’une opération à privilèges élevés qui doit être effectuée uniquement si elle est nécessaire dans votre scénario.This is a high privilege operation and should only be done if necessary for your scenario.

Pour voir un exemple de code qui implémente les étapes, consultez l’exemple d’étendues restreintes aux administrateurs.To see a code sample that implements the steps, see the admin-restricted scopes sample.

Demander les autorisations dans le portail d’inscription de l’applicationRequest the permissions in the app registration portal

Les applications sont en mesure de noter les autorisations dont elles ont besoin (autorisations déléguées et d'application) dans le portail d’inscription des applications.Applications are able to note which permissions they require (both delegated and application) in the app registration portal. Il est ainsi possible d’utiliser l’étendue /.default et l’option « Accorder un consentement administrateur » du portail Azure.This allows use of the /.default scope and the Azure portal's "Grant admin consent" option. En général, il est recommandé de veiller à ce que les autorisations définies de manière statique pour une application donnée constituent un sur-ensemble des autorisations qui seront demandées de façon dynamique/incrémentielle.In general, it's best practice to ensure that the permissions statically defined for a given application are a superset of the permissions that it will be requesting dynamically/incrementally.

Notes

Les autorisations d’application ne peuvent être demandées qu’à l’aide de /.default. Dès lors, si votre application requiert des autorisations d'application, vérifiez qu'elles sont répertoriées dans le portail d’inscription des applications.Application permissions can only be requested through the use of /.default - so if your app needs application permissions, make sure they're listed in the app registration portal.

Configuration de la liste des autorisations demandées de manière statique pour une applicationTo configure the list of statically requested permissions for an application

  1. Accédez à votre application dans l’environnement Inscriptions d’applications du portail Azure ou créez une application, si ce n’est pas déjà fait.Go to your application in the Azure portal – App registrations experience, or create an app if you haven't already.
  2. Recherchez la section Autorisations des API et, dans les autorisations des API, cliquez sur Ajouter une autorisation.Locate the API Permissions section, and within the API permissions click Add a permission.
  3. Sélectionnez Microsoft Graph dans la liste des API disponibles, puis ajoutez les autorisations dont votre application a besoin.Select Microsoft Graph from the list of available APIs and then add the permissions that your app requires.
  4. Enregistrez l’inscription de l’application.Save the app registration.

En général, lorsque vous créez une application qui utilise le point de terminaison de consentement de l’administrateur, l’application doit disposer d’une page ou vue dans laquelle l’administrateur peut approuver ses autorisations.Typically, when you build an application that uses the admin consent endpoint, the app needs a page or view in which the admin can approve the app's permissions. Cette page peut faire partie du flux d’inscription de l’application, des paramètres de l’application, ou ce peut être un flux de connexion dédié.This page can be part of the app's sign-up flow, part of the app's settings, or it can be a dedicated "connect" flow. Dans de nombreux cas, il est judicieux pour l’application d’afficher la vue de « connexion » uniquement après qu’un utilisateur se soit connecté avec un compte Microsoft professionnel ou scolaire.In many cases, it makes sense for the app to show this "connect" view only after a user has signed in with a work or school Microsoft account.

Lorsque vous connectez l’utilisateur à votre application, vous pouvez identifier l’organisation à laquelle l’administrateur appartient, avant de lui demander d’approuver les autorisations nécessaires.When you sign the user into your app, you can identify the organization to which the admin belongs before asking them to approve the necessary permissions. Même si cela n’est pas strictement nécessaire, cela peut vous aider à créer une expérience plus intuitive pour les utilisateurs de l’organisation.Although not strictly necessary, it can help you create a more intuitive experience for your organizational users. Pour connecter l’utilisateur, suivez nos tutoriels sur le protocole de la plateforme d’identités Microsoft.To sign the user in, follow our Microsoft identity platform protocol tutorials.

Demander les autorisations à un administrateur d’annuaireRequest the permissions from a directory admin

Lorsque vous êtes prêt à demander les autorisations à l’administrateur de votre organisation, vous pouvez rediriger l’utilisateur vers le point de terminaison de consentement administrateur de la plateforme d’identités Microsoft.When you're ready to request permissions from your organization's admin, you can redirect the user to the Microsoft identity platform admin consent endpoint.

// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
&scope=
https://graph.microsoft.com/calendars.read
https://graph.microsoft.com/mail.send
ParamètreParameter ConditionCondition DescriptionDescription
tenant ObligatoireRequired Le client d’annuaire auquel vous souhaitez demander l’autorisation.The directory tenant that you want to request permission from. Peut être fourni au format GUID ou sous forme de nom convivial OU référencé de manière générique avec des organisations comme indiqué dans l’exemple.Can be provided in GUID or friendly name format OR generically referenced with organizations as seen in the example. N’utilisez pas « common », car les comptes personnels ne peuvent pas fournir le consentement de l’administrateur, sauf dans le contexte d’un locataire.Do not use 'common', as personal accounts cannot provide admin consent except in the context of a tenant. Pour garantir une meilleure compatibilité avec les comptes personnels qui gèrent les locataires, utilisez l’ID de locataire, dans la mesure du possible.To ensure best compatibility with personal accounts that manage tenants, use the tenant ID when possible.
client_id ObligatoireRequired L’ID (client) d’application attribué à votre application par l’environnement Inscriptions d’applications du portail Azure.The Application (client) ID that the Azure portal – App registrations experience assigned to your app.
redirect_uri ObligatoireRequired L'URI de redirection où vous souhaitez que la réponse soit envoyée pour être gérée par votre application.The redirect URI where you want the response to be sent for your app to handle. Il doit correspondre exactement à l’un des URI de redirection que vous avez inscrits dans le portail d’inscription des applications.It must exactly match one of the redirect URIs that you registered in the app registration portal.
state RecommandéRecommended Une valeur incluse dans la requête, qui sera également renvoyée dans la réponse de jeton.A value included in the request that will also be returned in the token response. Il peut s’agir d’une chaîne du contenu de votre choix.It can be a string of any content you want. Utilisez l’état pour encoder les informations sur l’état de l’utilisateur dans l’application avant la requête d’authentification, comme la page ou la vue sur laquelle ou laquelle il était positionné.Use the state to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
scope ObligatoireRequired Définit l’ensemble des autorisations demandées par l’application.Defines the set of permissions being requested by the application. Il peut s’agir d’étendues statiques (utilisant /.default) ou dynamiques.This can be either static (using /.default) or dynamic scopes. Cela peut inclure les étendues OIDC (openid, profile, email).This can include the OIDC scopes (openid, profile, email). S'il vous faut des autorisations d’application, vous devez utiliser /.default pour demander la liste d’autorisations configurée statiquement.If you need application permissions, you must use /.default to request the statically configured list of permissions.

À ce stade, Azure AD nécessite qu’un administrateur client se connecte pour terminer la demande.At this point, Azure AD requires a tenant administrator to sign in to complete the request. L’administrateur est invité à approuver toutes les autorisations que vous avez demandées dans le paramètre scope.The administrator is asked to approve all the permissions that you have requested in the scope parameter. Si vous avez utilisé une valeur (/.default) statique, celle-ci fonctionne comme le point de terminaison de consentement administrateur v 1.0 et demande un consentement pour toutes les étendues trouvées dans les autorisations requises pour l’application.If you've used a static (/.default) value, it will function like the v1.0 admin consent endpoint and request consent for all scopes found in the required permissions for the app.

Réponse correcteSuccessful response

Si l’administrateur approuve les autorisations pour votre application, la réponse correcte ressemble à ce qui suit :If the admin approves the permissions for your app, the successful response looks like this:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
ParamètreParameter DescriptionDescription
tenant Client d’annuaire ayant accordé à votre application les autorisations demandées au format GUID.The directory tenant that granted your application the permissions it requested, in GUID format.
state Une valeur incluse dans la requête qui sera également renvoyée dans la réponse de jeton.A value included in the request that also will be returned in the token response. Il peut s’agir d’une chaîne du contenu de votre choix.It can be a string of any content you want. La valeur d’état est utilisée pour coder les informations sur l’état de l’utilisateur dans l’application avant la requête d’authentification, comme la page ou l’écran sur lequel ou laquelle il était positionné.The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
admin_consent Sera défini sur True.Will be set to True.

Réponse d’erreurError response

Si l’administrateur n’approuve pas les autorisations pour votre application, la réponse d’échec ressemble à ce qui suit :If the admin does not approve the permissions for your app, the failed response looks like this:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
ParamètreParameter DescriptionDescription
error Une chaîne de code d’erreur pouvant être utilisée pour classer les types d’erreurs se produisant, et pouvant être utilisée pour intervenir face aux erreurs.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description Un message d’erreur spécifique qui peut aider un développeur à identifier la cause principale d’une erreur.A specific error message that can help a developer identify the root cause of an error.

Une fois que vous avez reçu une réponse correcte du point de terminaison de consentement de l’administrateur, votre application a acquis les autorisations qu’elle avait demandées.After you've received a successful response from the admin consent endpoint, your app has gained the permissions it requested. Vous pouvez alors demander un jeton pour la ressource souhaitée.Next, you can request a token for the resource you want.

Utilisation des autorisationsUsing permissions

Une fois que l’utilisateur accepte les autorisations pour votre application, cette dernière peut acquérir des jetons d’accès représentant l’autorisation de votre application à accéder, dans une certaine capacité, à une ressource.After the user consents to permissions for your app, your app can acquire access tokens that represent your app's permission to access a resource in some capacity. Un jeton d’accès peut être utilisé pour une ressource uniquement, mais l’encodage de ce jeton comporte les informations relatives à toutes les autorisations octroyées pour cette ressource à votre application.An access token can be used only for a single resource, but encoded inside the access token is every permission that your app has been granted for that resource. Pour acquérir un jeton d’accès, votre application peut transmettre une demande au point de terminaison des jetons de la plateforme d’identités Microsoft :To acquire an access token, your app can make a request to the Microsoft identity platform token endpoint, like this:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/mail.read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq..."
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

Vous pouvez utiliser le jeton d’accès obtenu dans les requêtes HTTP transmises à la ressource.You can use the resulting access token in HTTP requests to the resource. Il indique de façon fiable à la ressource que votre application dispose de l’autorisation appropriée pour effectuer une tâche spécifique.It reliably indicates to the resource that your app has the proper permission to perform a specific task.

Pour en savoir plus sur le protocole OAuth 2.0 et sur la méthode pour obtenir des jetons d’accès, consultez la page de Référence sur le protocole du point de terminaison de la plateforme d’identités Microsoft.For more information about the OAuth 2.0 protocol and how to get access tokens, see the Microsoft identity platform endpoint protocol reference.

Étendue /.defaultThe /.default scope

Vous pouvez utiliser l’étendue /.default pour faciliter la migration de vos applications à partir du point de terminaison v1.0 vers le point de terminaison de la plateforme d’identités Microsoft.You can use the /.default scope to help migrate your apps from the v1.0 endpoint to the Microsoft identity platform endpoint. Il s’agit d’une étendue intégrée pour chaque application qui fait référence à la liste statique des autorisations configurées sur l’inscription d’application.This is a built-in scope for every application that refers to the static list of permissions configured on the application registration. Une valeur scope``https://graph.microsoft.com/.default est fonctionnellement identique aux points de terminaison v1.0 resource=https://graph.microsoft.com, autrement dit elle demande un jeton avec les étendues sur Microsoft Graph auxquelles l’application s’est inscrite dans le portail Azure.A scope value of https://graph.microsoft.com/.default is functionally the same as the v1.0 endpoints resource=https://graph.microsoft.com - namely, it requests a token with the scopes on Microsoft Graph that the application has registered for in the Azure portal. Elle est créée à l’aide de l’URI de ressource + /.default (par exemple, si l’URI de ressource est https://contosoApp.com, l’étendue demandée est https://contosoApp.com/.default).It is constructed using the resource URI + /.default (e.g. if the resource URI is https://contosoApp.com, then the scope requested would be https://contosoApp.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.See the section on trailing slashes for cases where you must include a second slash to correctly request the token.

L’étendue /.default peut être utilisée dans n’importe quel flux OAuth 2.0, mais elle est nécessaire dans le flux On-Behalf-Of et le flux des informations d’identification du client, de même que lors de l’utilisation du point de terminaison de consentement administrateur v2 pour demander des autorisations d’application.The /.default scope can be used in any OAuth 2.0 flow, but is necessary in the On-Behalf-Of flow and client credentials flow, as well as when using the v2 admin consent endpoint to request application permissions.

Notes

Les clients ne peuvent pas combiner un consentement statique (/.default) et dynamique dans une seule demande.Clients can't combine static (/.default) and dynamic consent in a single request. Par conséquent, scope=https://graph.microsoft.com/.default+mail.read entraîne une erreur en raison de la combinaison des types d’étendues.Thus, scope=https://graph.microsoft.com/.default+mail.read will result in an error due to the combination of scope types.

L’étendue /.default déclenche le comportement de point de terminaison v1.0 également pour prompt=consent.The /.default scope triggers the v1.0 endpoint behavior for prompt=consent as well. Elle demande le consentement pour toutes les autorisations inscrites par l’application, quelle que soit la ressource.It requests consent for all permissions registered by the application, regardless of the resource. Si elle est incluse dans le cadre de la demande, l’étendue /.default retourne un jeton qui contient les étendues pour la ressource demandée.If included as part of the request, the /.default scope returns a token that contains the scopes for the resource requested.

Comme /.default est fonctionnellement identique au comportement du point de terminaison v1.0 axé sur resource, elle s’accompagne aussi du comportement de consentement du point de terminaison v1.0.Because /.default is functionally identical to the resource-centric v1.0 endpoint's behavior, it brings with it the consent behavior of the v1.0 endpoint as well. Autrement dit, /.default déclenche uniquement une invite de consentement si aucune autorisation n’a été accordée entre le client et la ressource par l’utilisateur.Namely, /.default only triggers a consent prompt if no permission has been granted between the client and the resource by the user. Si un tel consentement existe, un jeton qui contient toutes les étendues accordées par l’utilisateur pour cette ressource est alors retourné.If any such consent exists, then a token will be returned containing all scopes granted by the user for that resource. Toutefois, si aucune autorisation n’a été accordée, ou si le paramètre prompt=consent a été fourni, une invite de consentement s’affiche pour toutes les étendues inscrites par l’application cliente.However, if no permission has been granted, or the prompt=consent parameter has been provided, a consent prompt will be shown for all scopes registered by the client application.

Exemple 1 : L’utilisateur, ou l’administrateur de locataire, a accordé des autorisationsExample 1: The user, or tenant admin, has granted permissions

Dans cet exemple, l’utilisateur (ou un administrateur de locataire) a accordé au client les autorisations Microsoft Graph mail.read et user.read.In this example, the user (or a tenant administrator) has granted the client the Microsoft Graph permissions mail.read and user.read. Si le client envoie une demande pour scope=https://graph.microsoft.com/.default, aucune invite de consentement ne s’affiche, quel que soit le contenu des autorisations inscrites par les applications clientes pour Microsoft Graph.If the client makes a request for scope=https://graph.microsoft.com/.default, then no consent prompt will be shown regardless of the contents of the client applications registered permissions for Microsoft Graph. Un jeton contenant les étendues mail.read et user.read doit être retourné.A token would be returned containing the scopes mail.read and user.read.

Exemple 2 : L’utilisateur n’a pas accordé d’autorisations entre le client et la ressourceExample 2: The user hasn't granted permissions between the client and the resource

Dans cet exemple, aucun consentement pour l’utilisateur n’existe entre le client et Microsoft Graph.In this example, no consent for the user exists between the client and Microsoft Graph. 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.The client has registered for the user.read and contacts.read permissions, as well as the Azure Key Vault scope https://vault.azure.net/user_impersonation. Quand le client demande un jeton pour scope=https://graph.microsoft.com/.default, l’utilisateur voit un écran de consentement pour les étendues user.read, contacts.read et Key Vault user_impersonation.When the client requests a token for scope=https://graph.microsoft.com/.default, the user will see a consent screen for the user.read, contacts.read, and the Key Vault user_impersonation scopes. Le jeton renvoyé présente uniquement les étendues user.read et contacts.read, et peut uniquement être utilisé sur Microsoft Graph.The token returned will have just the user.read and contacts.read scopes in it and only be usable against Microsoft Graph.

Exemple 3 : L’utilisateur a donné son consentement et le client demande des étendues supplémentairesExample 3: The user has consented and the client requests additional scopes

Dans cet exemple, l’utilisateur a déjà donné son consentement à mail.read pour le client.In this example, the user has already consented to mail.read for the client. Le client s’est inscrit à l’étendue contacts.read dans son inscription.The client has registered for the contacts.read scope in its registration. Lorsque le client effectue une demande pour un jeton à l’aide de scope=https://graph.microsoft.com/.default et demande un consentement via prompt=consent, l’utilisateur voit un écran de consentement uniquement pour toutes (et uniquement) les autorisations inscrites par l’application.When the client makes a request for a token using scope=https://graph.microsoft.com/.default and requests consent through prompt=consent, then the user will see a consent screen for all (and only) the permissions registered by the application. contacts.read est présent dans l’écran de consentement, mais pas mail.read.contacts.read will be present in the consent screen, but mail.read will not. Le jeton retourné concerne Microsoft Graph et contient mail.read et contacts.read.The token returned will be for Microsoft Graph and will contain mail.read and contacts.read.

Utilisation de l’étendue /.default avec le clientUsing the /.default scope with the client

Il existe un cas spécial d’étendue /.default quand un client demande sa propre étendue /.default.A special case of the /.default scope exists where a client requests its own /.default scope. L’exemple suivant illustre ce cas de figure.The following example demonstrates this scenario.

// 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=9ada6f8a-6d83-41bc-b169-a306c21527a5
&scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
&redirect_uri=https%3A%2F%2Flocalhost
&state=1234

Cela génère un écran de consentement pour toutes les autorisations inscrites (si cela est applicable en fonction des descriptions ci-dessus du consentement et de /.default), puis retourne un jeton id_token, plutôt qu’un jeton d’accès.This produces a consent screen for all registered permissions (if applicable based on the above descriptions of consent and /.default), then returns an id_token, rather than an access token. Ce comportement existe pour certains clients hérités qui passent de la bibliothèque ADAL à la bibliothèque MSAL et ne doit pas être utilisé par les nouveaux clients ciblant le point de terminaison de la plateforme d’identités Microsoft.This behavior exists for certain legacy clients moving from ADAL to MSAL, and should not be used by new clients targeting the Microsoft identity platform endpoint.

Barre oblique de fin et /.defaultTrailing slash and /.default

Certains URI de ressource sont dotés d'une barre oblique de fin (https://contoso.com/ par opposition à https://contoso.com), ce qui peut entraîner des problèmes de validation des jetons.Some resource URIs have a trailing slash (https://contoso.com/ as opposed to https://contoso.com), which can cause problems with token validation. Cela survient principalement en cas de demande de jeton pour la gestion des ressources Azure (https://management.azure.com/), qui présente une barre oblique de fin dans leur URI de ressource et dont la présence est requise lorsque le jeton est demandé.This can occur primarily when requesting a token for Azure Resource Management (https://management.azure.com/), which has a trailing slash on their resource URI and requires it to be present when the token is requested. Ainsi, en cas de demande de jeton pour https://management.azure.com/ et à l'aide de /.default, vous devez demander https://management.azure.com//.default (notez de la double barre oblique).Thus, when requesting a token for https://management.azure.com/ and using /.default, you must request https://management.azure.com//.default - note the double slash!

En général, si vous avez validé l'émission du jeton et que celui-ci est rejeté par l’API qui doit l’accepter, ajoutez une deuxième barre oblique, puis réessayez.In general - if you've validated that the token is being issued, and the token is being rejected by the API that should accept it, consider adding a second slash and trying again. Cela est dû au fait que le serveur de connexion émet un jeton avec une audience correspondant aux URI du paramètre scope, avec suppression de /.default.This happens because the login server emits a token with the audience matching the URIs in the scope parameter - with /.default removed from the end. Si cette opération supprime la barre oblique de fin, le serveur de connexion continue de traiter la demande et la valide par rapport à l’URI de ressource, même s’ils ne correspondent plus, ce qui n'est pas conforme.If this removes the trailing slash, the login server still processes the request and validates it against the resource URI, even though they no longer match - this is non-standard and should not be relied on by your application.

Si vous, ou les utilisateurs de votre application, constatez des erreurs inattendues au cours du processus de consentement, consultez cet article pour connaître les étapes de dépannage : Erreur inattendue lors du consentement à une application.If you or your application's users are seeing unexpected errors during the consent process, see this article for troubleshooting steps: Unexpected error when performing consent to an application.