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

  • Article

La plateforme d’identité Microsoft implémente le protocole d’autorisation OAuth 2.0. 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 allez découvrir les étendues et les autorisations dans la plateforme d’identités.

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

Cela s’applique également aux ressources tierces intégrées à la plateforme d’identité Microsoft. Ces ressources peuvent également définir un ensemble d’autorisations à utiliser pour diviser la fonctionnalité de cette ressource en fragments plus réduits. Par exemple, Microsoft Graph a défini des autorisations pour effectuer les tâches suivantes, entre autres :

  • 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.

Dans OAuth 2.0, ces types de jeux d’autorisations sont appelés des étendues. Ils sont également souvent appelés autorisations. 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.

Dans les requêtes adressées au serveur d’autorisation, pour la plateforme d’identités Microsoft, si l’identificateur de ressources est omis dans le paramètre d’étendue, la ressource est censée être Microsoft Graph. Par exemple, scope=User.Read équivaut à https://graph.microsoft.com/User.Read.

Autorisations restreintes aux administrateurs

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 l’annuaire d’une organisation

Remarque

Dans les requêtes adressées aux points de terminaison d’autorisation, de jeton ou de consentement pour la plateforme d’identités Microsoft, si l’identificateur de ressources est omis dans le paramètre d’étendue, la ressource est censée être Microsoft Graph. Par exemple, scope=User.Read équivaut à https://graph.microsoft.com/User.Read.

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. L’application cliente reçoit les autorisations directement. 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.

Si vous demandez les étendues OpenID Connect et un jeton, vous obtenez un jeton pour appeler le point de terminaison UserInfo.

Étendue openid

Si une application se connecte à l’aide d’OpenID Connect, elle doit solliciter l’étendue openid. L’étendue openid s’affiche sur la page de consentement du compte professionnel en tant qu’autorisation de connexion.

En utilisant cette autorisation, une application peut 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.

É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.

É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 le prénom de l’utilisateur, son nom de famille, son nom d’utilisateur préféré 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 référence id_tokens.

É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.

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

Notes

Cette autorisation apparaît actuellement sur toutes les pages de consentement, même pour les flux qui ne fournissent pas de jeton d’actualisation (par exemple, le flux implicite). Cette configuration concerne 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.

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. Ainsi, lorsque vous acceptez 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.

Le jeton d’accès est généralement valide pendant une heure environ. À ce stade, votre application doit rediriger l’utilisateur vers le point de terminaison /authorize pour demander un nouveau code d’autorisation. Pendant ce réacheminement et en fonction du type d’application, l’utilisateur devra peut-être entrer à nouveau ses informations d’identification ou consentir une nouvelle fois aux autorisations.

Le jeton d’actualisation a une expiration plus longue que le jeton d’accès et est généralement valide une journée. 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.

É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).

L’étendue .default peut être utilisée dans n’importe quel flux OAuth 2.0 et pour initier le consentement administrateur. Il est nécessaire dans le flux On-Behalf-Of et le flux d’informations d’identification du client.

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.

Le paramètre d’étendue .default déclenche une invite de consentement uniquement si le consentement n’a pas été accordé pour une autorisation déléguée entre le client et la ressource, pour le compte 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 a été 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é octroyée pour Microsoft Graph pour le compte de l’utilisateur connecté, la connexion se poursuit et toutes les autorisations déléguées à Microsoft Graph octroyées à 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 s’affiche 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 pour les autorisations User.Read et Contacts.Read. Il s’est également inscrit pour l’étendue d’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, l’invite de consentement s’affiche. (Dans le cas contraire, un message d’erreur ou le formulaire de demande de consentement de l’administrateur s’affichent.) Contacts.Read et Mail.Read se trouveront 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.

Cette configuration ne doit pas être utilisée par les nouveaux clients qui ciblent la plateforme d’identités Microsoft. Veillez à migrer vers la bibliothèque d’authentification Microsoft (MSAL) à partir de la bibliothèque d’authentification Azure AD (ADAL).

Flux d’octroi d’informations d’identification de client et .default

Une autre utilisation de .default consiste à demander des rôles d’application (ou des autorisations d’application) dans une application non interactive telle qu’une application démon qui utilise le flux d’octroi des informations d’identification du client pour appeler une API web.

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.

Les demandes d’informations d’identification du client dans votre service client doivent inclure 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. L’émission d’une demande d’informations d’identification du client à l’aide de permissions d’application individuelles (rôles) n’est pas prise en charge. 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.

Voir aussi