Autorisations et consentement dans la plateforme d’identités Microsoft
Les applications qui s’intègrent à la plateforme d’identités Microsoft suivent un modèle d’autorisation permettant aux utilisateurs et aux administrateurs de contrôler l’accès aux données. L’implémentation de ce modèle d’autorisation a été mise à jour sur la plateforme d’identités Microsoft. Elle modifie la manière dont une application doit interagir avec la plateforme d’identités Microsoft. Cet article aborde les concepts de base de ce modèle d’autorisation, notamment les étendues, les autorisations et le consentement.
Étendues et autorisations
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.
Voici quelques exemples de ressources Microsoft hébergées sur le web :
- 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é 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.
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. Toutefois, certaines autorisations à privilèges élevés peuvent être accordées uniquement par le biais du consentement de l’administrateur. Elles peuvent être demandées ou accordées en utilisant le point de terminaison de consentement de l’administrateur. Poursuivez votre lecture pour en savoir plus.
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 ressource 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
.
Types d'autorisations
La plateforme d’identités Microsoft prend en charge deux types d’autorisations : les permissions déléguées et les permissions d’application.
Les autorisations déléguées sont utilisées par les applications pour lesquelles un utilisateur est connecté et présent. Pour ces applications, l’utilisateur ou un administrateur consent aux autorisations demandées par l’application. L’application se voit déléguer la permission d’agir en tant qu’utilisateur connecté lorsqu’elle effectue des appels vers la ressource cible.
Certaines permissions déléguées peuvent être consenties par des non-administrateurs. Toutefois, certaines autorisations à privilèges élevés requièrent le consentement de l’administrateur. Pour connaître les rôles Administrateur habilités à donner leur consentement pour les permissions déléguées, consultez Autorisations du rôle Administrateur dans Azure Active Directory (Azure AD).
Les permissions d’application sont utilisées par les applications qui s’exécutent sans qu’un utilisateur soit connecté et présent, par exemple, les applications qui s’exécutent en tant que services ou démons en arrière-plan. Seul un administrateur peut consentir aux permissions d’application.
Les autorisations effectives correspondent aux autorisations dont dispose votre application lorsqu’elle envoie des requêtes à une ressource cible. Vous devez comprendre la différence entre les permissions déléguées et les permissions d’application accordées à votre application et les autorisations effectives accordées à votre application lorsqu’elle effectue des appels vers la ressource cible.
Pour les permissions déléguées, les autorisations effectives de votre application correspondent au niveau de privilège le moins élevé entre les permissions 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é. Votre application ne peut jamais avoir plus de privilèges que l’utilisateur connecté.
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 Administrateur. 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.
Supposons que votre application ait reçu l’autorisation déléguée User.ReadWrite.All. Cette autorisation permet nominalement à votre application de lire et mettre à jour le profil de chaque utilisateur dans une organisation. Si l’utilisateur connecté est un administrateur général, votre application peut mettre à jour le profil de chaque utilisateur de l’organisation. Toutefois, si l’utilisateur connecté n’a pas de rôle Administrateur, votre application peut uniquement mettre à jour le profil de l’utilisateur connecté. 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.
Pour les permissions d’application, les autorisations effectives de votre application correspondent au niveau complet des privilèges impliqués par l’autorisation. Par exemple, une application disposant de l’autorisation d’application User.ReadWrite.All peut mettre à jour le profil de chaque utilisateur de l’organisation.
É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.
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.
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.
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 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 référence id_tokens
.
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 valide pendant une courte durée : il arrive généralement à expiration en une heure. À ce stade, votre application doit rediriger l’utilisateur vers le point de terminaison /authorize
afin de récupérer un nouveau code d’autorisation. 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.
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.
Types de consentement
Les applications de la plateforme d’identités Microsoft s’appuient sur le consentement pour accéder aux ressources ou aux API nécessaires. Il existe plusieurs types de consentement dont votre application peut avoir besoin pour fonctionner correctement. Si vous définissez des autorisations, vous devez également comprendre la façon dont vos utilisateurs vont accéder à votre application ou API.
Consentement de l’utilisateur statique
Dans le scénario du consentement de l’utilisateur statique, vous devez spécifier toutes les autorisations nécessaires dans la configuration de l’application, au sein du portail Azure. Si l’utilisateur (ou l’administrateur, selon le cas) n’a pas octroyé son consentement pour cette application, la plateforme d’identités Microsoft invite l’utilisateur à donner son consentement à ce stade.
Les autorisations statiques permettent également aux administrateurs de donner leur consentement au nom de tous les utilisateurs de l’organisation.
Bien que les autorisations statiques de l’application définies dans le portail Azure préservent la simplicité du code, elles présentent quelques problèmes potentiels pour les développeurs :
L’application doit demander toutes les autorisations dont elle est susceptible d’avoir besoin dès la première connexion de l’utilisateur. Ceci peut résulter en une longue liste d’autorisations qui décourage les utilisateurs finaux d’approuver l’accès de l’application lors de la connexion initiale.
L’application doit connaître au préalable l’ensemble des ressources auxquelles elle est susceptible d’accéder. Il est difficile de créer des applications pouvant accéder à un nombre arbitraire de ressources.
Consentement de l’utilisateur incrémentiel et dynamique
Avec le point de terminaison de la Plateforme d’identités Microsoft, vous pouvez ignorer les autorisations statiques définies dans les informations d’inscription de l’application du portail Azure et demander à la place des autorisations de façon incrémentielle. Vous pouvez demander dès le départ un ensemble minimal d’autorisations, puis en demander plus ultérieurement quand le client utilise des fonctionnalités d’application supplémentaires. Pour cela, vous pouvez spécifier les étendues dont votre application a besoin à tout moment en incluant les nouvelles étendues dans le paramètre scope
quand vous demandez un jeton d’accès, sans qu’il soit nécessaire de les définir au préalable dans les informations d’inscription de l’application. Si l’utilisateur n’a pas encore consenti aux nouvelles étendues ajoutées à la demande, il est invité à donner son consentement seulement aux nouvelles autorisations. Consentement incrémentiel ou dynamique, s’applique uniquement aux autorisations déléguées et pas aux permissions d’application.
En permettant à l’application de demander des autorisations de façon dynamique grâce au paramètre scope
, les développeurs maîtrisent totalement l’expérience de vos utilisateurs. Vous pouvez aussi anticiper l’expérience de consentement et demander toutes les autorisations dans une même demande d’autorisation initiale. Si votre application nécessite un grand nombre d’autorisations, vous pouvez les demander à l’utilisateur de façon incrémentielle quand il essaie d’utiliser certaines fonctionnalités de votre application au fil du temps.
Important
Le consentement dynamique peut être pratique, mais présente un défi de taille pour les autorisations qui nécessitent le consentement de l’administrateur. L’expérience de consentement de l’administrateur dans les panneaux Inscriptions d’applications et Applications d’entreprise du portail n’a pas connaissance de ces autorisations dynamiques au moment du consentement. Nous recommandons à un développeur de répertorier toutes les autorisations d’administrateur nécessaires à l’application dans le portail. Cela permet aux administrateurs de locataires de donner leur consentement au nom de tous leurs utilisateurs dans le portail, une seule fois. Les utilisateurs n’ont pas besoin de parcourir l’expérience de consentement pour ces autorisations sur la connexion. L’alternative consiste à utiliser le consentement dynamique pour ces autorisations. Pour accorder le consentement de l’administrateur, un administrateur individuel se connecte à l’application, déclenche une invite de consentement pour les autorisations appropriées et sélectionne Consentement pour l’organisation entière dans la boîte de dialogue de consentement.
Consentement de l’administrateur
Consentement administrateur : nécessaire quand votre application a besoin d’accéder à certaines autorisations dotées de privilèges élevés. Le consentement de l’administrateur garantit que les administrateurs disposent de contrôles supplémentaires avant d’autoriser des applications ou des utilisateurs à accéder aux données à privilèges élevés de l’organisation.
Le consentement administrateur effectué pour le compte d’une organisation est fortement recommandé si votre application a un public d’entreprise. Le consentement administrateur accordé au nom d’une organisation nécessite toujours l’inscription des autorisations statiques pour l’application dans le portail. Définissez ces autorisations pour les applications dans le portail d’inscription d’applications, si vous avez besoin qu’un administrateur donne son consentement au nom de l’ensemble de l’organisation. L’administrateur peut donner son consentement à ces autorisations pour le compte de tous les utilisateurs de l’organisation, en une seule fois. Les utilisateurs n’ont pas besoin de parcourir l’expérience de consentement pour ces autorisations lors de la connexion à l’application. Cela est plus facile pour les utilisateurs, et les cycles nécessaires à l’administrateur de l’organisation pour configurer l’application sont réduits.
Demande de consentement d’utilisateur individuel
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
. Par exemple, lorsqu’un utilisateur se connecte à une application, cette dernière envoie une requête semblable à l’exemple ci-dessous. (Des sauts de ligne sont ajoutés pour une meilleure lisibilité.)
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. Chaque autorisation est indiquée par l’ajout de la valeur correspondante à l’identificateur de la ressource (URI d’ID d’application). 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.
Une fois que l’utilisateur a entré ses informations d’identification, la plateforme d’identités Microsoft recherche un enregistrement correspondant du consentement de l’utilisateur. Si, par le passé, l’utilisateur n’a consenti à aucune des autorisations demandées et que l’administrateur n’a pas consenti à ces autorisations pour le compte de toute l’organisation, la plateforme d’identités Microsoft demande à l’utilisateur d’accorder les autorisations demandées.
À 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. Ces autorisations sont généralement requises pour le bon fonctionnement de l’application. L’autorisation offline_access
donne à l’application l’accès à des jetons d’actualisation qui sont essentiels pour les applications natives et les applications web. L’autorisation User.Read
donne accès à la revendication sub
. Elle permet au client ou à l’application d’identifier correctement l’utilisateur au fil du temps et d’accéder à des informations rudimentaires sur l’utilisateur.
Lorsque l’utilisateur approuve la demande d’autorisation, le consentement est enregistré. L’utilisateur n’a plus à donner son consentement lorsqu’il se connecte ultérieurement à l’application.
Demande de consentement d’un client entier
Lorsqu’une organisation achète une licence ou un abonnement pour une application, elle souhaite souvent configurer l’application de manière proactive afin que tous les membres de l’organisation puissent l’utiliser. 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. 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.
Le consentement administrateur accordé au nom d’une organisation nécessite toujours l’inscription des autorisations statiques pour l’application. Définissez ces autorisations pour les applications dans le portail d’inscription d’applications, si vous avez besoin qu’un administrateur donne son consentement au nom de l’ensemble de l’organisation.
Si vous souhaitez demander le consentement relatif aux autorisations déléguées pour tous les utilisateurs d’un locataire, votre application peut utiliser le point de terminaison de consentement administrateur.
En outre, les applications doivent utiliser le point de terminaison du consentement administrateur pour demander des permissions d’application.
Autorisations restreintes aux administrateurs
Certaines autorisations à privilèges élevés dans les ressources Microsoft peuvent être définies sur restreintes aux administrateurs. Voici quelques exemples de ces types d’autorisations :
- Lire les profils complets de tous les utilisateurs à l’aide de
User.Read.All
- Écrire des données dans le répertoire d’une organisation à l’aide de
Directory.ReadWrite.All
- Lire tous les groupes dans le répertoire d’une organisation à l’aide de
Groups.Read.All
Notes
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 ressource 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 votre application requiert des étendues pour les autorisations restreintes aux administrateurs, l’administrateur d’une organisation doit donner son consentement à ces étendues pour le compte des utilisateurs de l’organisation. Pour éviter d’afficher des invites aux utilisateurs qui demandent un consentement pour les autorisations qu’ils ne peuvent pas accorder, votre application peut utiliser le point de terminaison du consentement administrateur. Le point de terminaison du consentement administrateur est abordé dans la section suivante.
Si l’application demande des permissions déléguées à privilèges élevés et qu’un administrateur accorde ces permissions via le point de terminaison du consentement administrateur, le consentement est accordé à tous les utilisateurs du locataire.
Si l’application demande des permissions d’application et qu’un administrateur accorde ces permissions via le point de terminaison du consentement administrateur, cette attribution n’est pas effectuée pour le compte d’un utilisateur spécifique. L’application cliente reçoit les autorisations directement. Ces types d’autorisations sont utilisés uniquement par les services démon et d’autres applications non interactives qui s’exécutent en arrière-plan.
Utilisation du point de terminaison de consentement administrateur
Une fois que vous avez utilisé le point de terminaison du consentement administrateur pour accorder le consentement administrateur, vous avez terminé. Les utilisateurs n’ont pas besoin d’effectuer d’autres actions. Une fois le consentement administrateur accordé, les utilisateurs peuvent obtenir un jeton d’accès par le biais d’un flux d’authentification standard. Le jeton d’accès obtenu possède les autorisations accordées.
Lorsqu’un administrateur général utilise votre application et est dirigé vers le point de terminaison d’autorisation, la plateforme d’identités Microsoft détecte le rôle de l’utilisateur. Elle demande si l’administrateur général souhaite donner son consentement pour le compte de l’ensemble du locataire aux autorisations que vous avez demandées. Vous pouvez utiliser à la place un point de terminaison du consentement administrateur dédié pour demander de manière proactive à un administrateur d’accorder l’autorisation pour le compte de l’ensemble du locataire. Ce point de terminaison est également nécessaire pour demander des permissions d’application. Les permissions d’application ne peuvent pas être demandées à l’aide du point de terminaison d’autorisation.
Si vous suivez ces étapes, votre application peut demander des autorisations pour tous les utilisateurs d’un locataire, notamment les étendues restreintes aux administrateurs. Cette opération demande des privilèges élevés. Utilisez l’opération uniquement si elle est nécessaire pour votre scénario.
Pour voir un exemple de code qui implémente les étapes, consultez l’exemple d’étendues restreintes aux administrateurs dans GitHub.
Demander les autorisations dans le portail d’inscription de l’application
Dans le portail d’inscription des applications, les applications peuvent répertorier les autorisations dont elles ont besoin, y compris les permissions déléguées et les permissions d’application. Cette configuration permet d’utiliser l’étendue .default
et l’option Accorder un consentement administrateur du portail Azure.
En général, les autorisations doivent être définies de manière statique pour une application donnée. Elles doivent être un sur-ensemble des autorisations demandées par l’application de manière dynamique ou incrémentielle.
Notes
Les permissions d’application ne peuvent être demandées qu’à l’aide de .default
. Dès lors, si votre application requiert des permissions d’application, vérifiez qu’elles sont répertoriées dans le portail d’inscription des applications.
Pour configurer la liste des autorisations demandées de manière statique pour une application :
- Accédez à votre application dans l’expérience de démarrage rapide Portail Azure – Inscriptions d’applications.
- Sélectionnez une application ou créez une application si vous ne l’avez pas déjà fait.
- Dans la page Vue d’ensemble de l’application, sous Gérer, sélectionnez Autorisations de l’API>Ajouter une autorisation.
- Sélectionnez Microsoft Graph dans la liste des API disponibles. Ajoutez ensuite les autorisations dont votre application a besoin.
- Sélectionnez Ajouter des autorisations.
Recommandé : connectez l’utilisateur à votre application
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. Cette page peut être :
- Une partie du flux d’inscription de l’application.
- Une partie des paramètres de l’application.
- Un flux de « connexion » dédié.
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 un compte Microsoft scolaire.
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. Même si cette étape n’est pas strictement nécessaire, elle peut vous aider à créer une expérience plus intuitive pour les utilisateurs de votre organisation.
Pour connecter l’utilisateur, suivez les tutoriels sur le protocole de la plateforme d’identités Microsoft.
Demander les autorisations à un administrateur d’annuaire
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.
// 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ètre | Condition | Description |
---|---|---|
tenant |
Obligatoire | Le client d’annuaire auquel vous souhaitez demander l’autorisation. Il peut être fourni sous forme de GUID ou de nom convivial. Il peut aussi être référencé de manière générique auprès des organisations, comme illustré dans l’exemple. N’utilisez pas « common », car les comptes personnels ne peuvent pas fournir de consentement administrateur, sauf dans le contexte d’un locataire. Pour garantir la meilleure compatibilité avec les comptes personnels qui gèrent les locataires, utilisez l’ID de locataire, dans la mesure du possible. |
client_id |
Obligatoire | L’ID (client) d’application attribué à votre application par l’expérience Portail Azure – Inscriptions d’applications. |
redirect_uri |
Obligatoire | L'URI de redirection où vous souhaitez que la réponse soit envoyée pour être gérée par votre application. Il doit correspondre exactement à l’un des URI de redirection que vous avez inscrits dans le portail d’inscription des applications. |
state |
Recommandé | Une valeur incluse dans la requête, qui sera également renvoyée dans la réponse de jeton. Il peut s’agir d’une chaîne du contenu de votre choix. 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é. |
scope |
Obligatoire | Définit l’ensemble des autorisations demandées par l’application. Les étendues peuvent être statiques (utilisant .default ) ou dynamiques. Cet ensemble peut inclure les étendues OpenID Connect (openid , profile , email ). S'il vous faut des autorisations d’application, vous devez utiliser .default pour demander la liste d’autorisations configurée statiquement. |
À ce stade, Azure AD nécessite qu’un administrateur client se connecte pour terminer la demande. L’administrateur est invité à approuver toutes les autorisations que vous avez demandées dans le paramètre scope
. Si vous avez utilisé une valeur statique (.default
), celle-ci fonctionne comme le point de terminaison du consentement administrateur v1.0 et demande un consentement pour toutes les étendues trouvées dans les autorisations requises pour l’application.
Réponse correcte
Si l’administrateur approuve les autorisations pour votre application, la réponse correcte ressemble à ce qui suit :
GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
Paramètre | Description |
---|---|
tenant |
Client d’annuaire ayant accordé à votre application les autorisations demandées au format GUID. |
state |
Une valeur incluse dans la requête qui sera également renvoyée dans la réponse de jeton. Il peut s’agir d’une chaîne du contenu de votre choix. 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é. |
admin_consent |
Sera défini sur True . |
Réponse d’erreur
Si l’administrateur n’approuve pas les autorisations pour votre application, la réponse d’échec ressemble à ce qui suit :
GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Paramètre | Description |
---|---|
error |
Une chaîne de code d’erreur qui peut être utilisée pour classer les types d’erreurs qui se produisent. Elle peut également être utilisée pour réagir aux erreurs. |
error_description |
Un message d’erreur spécifique qui peut aider un développeur à identifier la cause principale d’une erreur. |
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. Vous pouvez alors demander un jeton pour la ressource souhaitée.
Utilisation des autorisations
Une fois que l’utilisateur consent aux autorisations pour votre application, cette dernière peut acquérir des jetons d’accès représentant l’autorisation de l’application à accéder, dans une certaine capacité, à une ressource. Un jeton d’accès ne peut être utilisé que pour une seule ressource. Toutefois, l’encodage de ce jeton comporte les informations relatives à toutes les autorisations accordées à votre application pour cette ressource. 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 :
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. Il indique de façon fiable à la ressource que votre application dispose de l’autorisation appropriée pour effectuer une tâche spécifique.
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.
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).
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.
.default quand l’utilisateur a déjà donné son consentement
L’étendue .default
est fonctionnellement identique au comportement du point de terminaison v1.0 centré sur resource
. Elle porte également le comportement de consentement du point de terminaison v1.0. Autrement dit, .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 accordé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é accordé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 accordé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=9ada6f8a-6d83-41bc-b169-a306c21527a5
&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.
Ce comportement prend en charge certains clients hérités qui passent de Bibliothèque d’authentification Azure AD (ADAL) à Bibliothèque d’authentification Microsoft (MSAL). Cette configuration ne doit pas être utilisée par les nouveaux clients qui ciblent la plateforme d’identités Microsoft.
Flux d’octroi des informations d’identification du 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.
Résolution des problèmes d’autorisations et de consentement
Pour connaître les étapes de résolution des problèmes, consultez Erreur inattendue lors de l’exécution du consentement sur une application.