Partager via

Guide du développeur pour demander des autorisations et un consentement dans La plateforme d’identités Microsoft

Les applications de la plateforme d’identités Microsoft s’appuient sur le consentement pour accéder aux ressources ou API nécessaires. Différents types de consentement sont préférables pour différents scénarios d’application. Le choix de la meilleure approche pour donner votre consentement à votre application lui permet d’être plus efficace avec les utilisateurs et les organisations.

Dans cet article, vous allez découvrir les différents types de consentement et comment demander des autorisations pour votre application par le biais du consentement.

Dans le scénario de consentement de l’utilisateur statique, vous devez spécifier toutes les autorisations dont elle a besoin dans la configuration de l’application dans le Centre d’administration Microsoft Entra. Si l’utilisateur (ou l’administrateur, le cas échéant) n’accorde pas de consentement pour cette application, la plateforme d’identités Microsoft invite l’utilisateur à fournir son consentement pour l’instant.

Les autorisations statiques permettent également aux administrateurs de donner leur consentement au nom de tous les utilisateurs de l’organisation.

Tout en s’appuyant sur le consentement statique et une liste d’autorisations unique conserve le code bien et simple, cela signifie également que votre application demande toutes les autorisations dont elle peut avoir besoin avant. Ce paramètre peut empêcher les utilisateurs et les administrateurs d’approuver la demande d’accès de votre application.

Avec l'endpoint de la plateforme d'identité Microsoft, vous pouvez ignorer les autorisations statiques définies dans les informations d'inscription d'application dans le Microsoft Entra admin center. Au lieu de cela, vous pouvez demander des autorisations de manière incrémentielle. Vous pouvez demander un ensemble minimal d’autorisations au préalable et demander plus au fil du temps, car le client utilise davantage de fonctionnalités d’application. Pour ce faire, vous pouvez spécifier les étendues dont votre application a besoin à tout moment en incluant les nouvelles étendues du paramètre lors de la scopedemande d’un jeton d’accès , sans avoir à les prédéfinir dans les informations d’inscription de l’application.

Si l’utilisateur ne consent pas aux nouvelles étendues ajoutées à la demande, il reçoit une invite pour donner son consentement uniquement aux nouvelles autorisations. Le consentement incrémentiel ou dynamique s’applique uniquement aux autorisations déléguées et non aux autorisations d’application.

L’autorisation d’une application pour demander des autorisations dynamiquement via le scope paramètre donne aux développeurs un contrôle total sur l’expérience de votre utilisateur. Vous chargez avant votre expérience de consentement et demandez toutes les autorisations dans une demande d’autorisation initiale. Si votre application nécessite un grand nombre d’autorisations, vous pouvez collecter ces autorisations auprès de l’utilisateur de manière incrémentielle, car elle tente d’utiliser certaines fonctionnalités de l’application au fil du temps.

Important

Le consentement dynamique peut être pratique, mais présente un défi significatif pour les autorisations qui nécessitent le consentement de l’administrateur. L'expérience de consentement de l'administrateur dans les Inscriptions d'applications et Applications d'entreprise du portail ne prend pas en compte ces autorisations dynamiques au moment du consentement. Nous vous recommandons de répertorier toutes les autorisations privilégiées par l’administrateur dont l’application a besoin dans le portail.

Cela permet aux administrateurs de locataires de donner leur consentement pour le compte de tous leurs utilisateurs dans le portail une seule fois. Les utilisateurs n’ont pas besoin de passer par l’expérience de consentement pour ces autorisations lors de 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 le consentement pour l’ensemble de mon organisation dans le dialogue de consentement.

Dans une demande d’autorisation OpenID Connect ou OAuth 2.0 , une application peut demander les autorisations dont elle a besoin à l’aide du scope paramètre de requête. Par exemple, lorsqu’un utilisateur se connecte à une application, l’application envoie une demande comme l’exemple suivant. (Les sauts de ligne sont ajoutés pour la lisibilité).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&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 scope paramètre est une liste séparée par l’espace des autorisations déléguées 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 demande, l’application a besoin de l’autorisation de lire le calendrier de l’utilisateur et d’envoyer du courrier en tant qu’utilisateur.

Après la connexion, la plateforme d’identités Microsoft vérifie le consentement de l’utilisateur existant. Si l’utilisateur n’approuve pas les autorisations demandées et qu’un administrateur ne les approuve pas non plus, la plateforme invite l’utilisateur à accorder son consentement.

Dans l’exemple suivant, l’autorisation offline_access (« Maintenir l’accès aux données auxquels vous accordez l’accès ») et User.Read l’autorisation (« Se connecter et lire votre profil ») sont automatiquement incluses dans le consentement initial d’une application. Ces autorisations sont requises pour les fonctionnalités d’application appropriées.

L’autorisation offline_access donne à l’application l’accès aux jetons d’actualisation qui sont essentiels pour les applications natives et les applications web. L’autorisation User.Read donne accès à la sub réclamation. Il permet au client ou à l’application d’identifier correctement l’utilisateur au fil du temps et d’accéder aux informations utilisateur rudimentaires.

Exemple de capture d’écran montrant le consentement du compte professionnel.

Lorsque l’utilisateur approuve la demande d’autorisation, le consentement est enregistré. L’utilisateur n’a pas à consentir à nouveau lorsqu’il se connecte ultérieurement à l’application.

La demande de consentement pour un locataire entier nécessite le consentement de l’administrateur. Le consentement administrateur effectué pour le compte d’une organisation nécessite les autorisations statiques inscrites pour l’application. Définissez ces autorisations dans le portail d’inscription d’application si vous avez besoin d’un administrateur pour donner votre consentement au nom de l’ensemble de l’organisation.

Lorsque votre application demande des autorisations déléguées qui nécessitent le consentement de l’administrateur, les utilisateurs voient une erreur « non autorisé à donner leur consentement » et doivent demander à un administrateur d’accéder. Une fois qu’un administrateur accorde le consentement pour l’ensemble du locataire, les utilisateurs ne sont pas invités à nouveau, sauf si le consentement est révoqué ou que de nouvelles autorisations sont ajoutées.

Les administrateurs utilisant la même application voient l’invite de consentement de l’administrateur. L’invite de consentement administrateur fournit une case à cocher qui leur permet d’accorder à l’application l’accès aux données demandées pour le compte des utilisateurs pour l’ensemble du locataire. Pour plus d’informations sur l’expérience de consentement de l’utilisateur et de l’administrateur, consultez l’expérience de consentement de l’application.

Voici quelques exemples d’autorisations déléguées pour Microsoft Graph qui nécessitent le consentement de l’administrateur :

  • 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

Pour afficher la liste complète des autorisations Microsoft Graph, consultez la référence des autorisations Microsoft Graph.

Vous pouvez également configurer des autorisations sur vos propres ressources pour exiger le consentement de l’administrateur. Pour plus d’informations sur l’ajout d’étendues qui nécessitent le consentement de l’administrateur, consultez Ajouter une étendue qui nécessite le consentement de l’administrateur.

Certaines organisations peuvent modifier la stratégie de consentement utilisateur par défaut pour le locataire. Lorsque votre application demande l'accès à des autorisations, celles-ci sont évaluées par rapport à ces stratégies. L’utilisateur peut avoir besoin de demander le consentement de l’administrateur, même s’il n’est pas requis par défaut. Pour savoir comment les administrateurs gèrent les stratégies de consentement pour les applications, consultez Gérer les stratégies de consentement des applications.

Remarque

Dans les demandes d’autorisation, de jeton ou de consentement de la plateforme d’identités Microsoft, omettez l’identificateur de ressource dans les scope paramètres par défaut pour Microsoft Graph. Par exemple, scope=User.Read est traitée comme https://graph.microsoft.com/User.Read.

Les autorisations d’application nécessitent toujours le consentement de l’administrateur. Les autorisations d’application n’ont pas de contexte utilisateur et l’octroi de consentement n’est pas effectué pour le compte d’un utilisateur spécifique. Les autorisations sont à la place directement octroyées à l’application cliente. 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. Les administrateurs doivent configurer les autorisations initialement et accorder le consentement de l’administrateur via le Centre d’administration Microsoft Entra.

Si l’application demandant l’autorisation est une application mutualisée, son inscription d’application existe uniquement dans le locataire où elle a été créée, par conséquent, les autorisations ne peuvent pas être configurées dans le locataire local. Si l’application demande des autorisations qui nécessitent le consentement de l’administrateur, l’administrateur doit donner son consentement pour le compte des utilisateurs. Pour consentir à ces autorisations, les administrateurs doivent se connecter à l’application eux-mêmes, de sorte que l’expérience de connexion de consentement de l’administrateur est déclenchée. Pour savoir comment configurer l’expérience de consentement administrateur pour les applications multilocataires, consultez Activer les connexions multilocataires

Un administrateur peut accorder le consentement d’une application avec les options suivantes.

En règle générale, lorsque vous créez une application qui nécessite le consentement de l’administrateur, l’application a besoin d’une page ou d’une vue dans laquelle l’administrateur peut approuver les autorisations de l’application. Cette page peut être :

  • Partie du flux d’inscription de l’application.
  • Partie des paramètres de l’application.
  • Flux dédié de « connexion ».

Dans de nombreux cas, il est judicieux que l’application affiche l’affichage « se connecter » uniquement une fois qu’un utilisateur est connecté avec un compte Microsoft professionnel ou un compte Microsoft scolaire.

Lorsque vous connectez l’utilisateur à votre application, vous pouvez identifier l’organisation à laquelle appartient l’administrateur avant de lui demander d’approuver les autorisations nécessaires. Bien que cette étape ne soit pas strictement nécessaire, elle peut vous aider à créer une expérience plus intuitive pour vos utilisateurs organisationnels.

Pour connecter l’utilisateur, suivez les tutoriels sur le protocole de la plateforme d’identités Microsoft.

Demander les autorisations dans le portail d’inscription de l’application

Dans le portail d’inscription d’application, les applications peuvent répertorier les autorisations dont elles ont besoin, y compris les autorisations déléguées et les autorisations d’application. Cette configuration permet d'utiliser l'étendue .default et l'option Accorder le consentement administrateur du centre d'administration Microsoft Entra.

En général, les autorisations doivent être définies de manière statique pour une application donnée. Il doit s’agir d’un sur-ensemble des autorisations demandées dynamiquement ou de manière incrémentielle par l’application.

Remarque

Les autorisations d’application peuvent être demandées uniquement à l’aide .defaultde . Par conséquent, si votre application a besoin d’autorisations d’application, vérifiez qu’elles sont répertoriées dans le portail d’inscription d’application.

Pour configurer la liste des autorisations demandées statiquement pour une application :

  1. Connectez-vous au Centre d’administration de Microsoft Entra au minimum en tant qu’Administrateur d’application cloud.
  2. Accédez à Entra ID>Inscriptions d'applications>Toutes les applications.
  3. Sélectionnez une application ou créez une application si vous ne l’avez pas déjà fait.
  4. Dans la page Vue d’ensemble de l’application, sous Gérer, sélectionnez Autorisations d’API>Ajouter une autorisation.
  5. Sélectionnez Microsoft Graph dans la liste des API disponibles. Ajoutez ensuite les autorisations requises par votre application.
  6. Sélectionnez Ajouter des autorisations.

Réponse réussie

Si l’administrateur approuve les autorisations pour votre application, la réponse réussie ressemble à ceci :

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Paramètre Descriptif
tenant Le locataire du répertoire qui a accordé à votre application les autorisations demandées, sous forme d'identifiant global unique (GUID).
state Valeur incluse dans la requête retournée dans la réponse du jeton. Il peut s’agir d’une chaîne du contenu de votre choix. L’état est utilisé pour encoder des informations sur l’état de l’utilisateur dans l’application avant que la demande d’authentification ne s’est produite, telle que la page ou la vue sur laquelle ils étaient activés.
admin_consent Est défini sur True.

Une fois que vous avez reçu une réponse réussie du point de terminaison de consentement administrateur, votre application reçoit les autorisations demandées. Ensuite, vous pouvez demander un jeton pour la ressource souhaitée.

Réponse d’erreur

Si l’administrateur n’approuve pas les autorisations pour votre application, la réponse ayant échoué ressemble à ceci :

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Paramètre Descriptif
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs qui se produisent. Il peut également être utilisé pour réagir aux erreurs.
error_description Message d’erreur spécifique qui peut aider un développeur à identifier la cause racine d’une erreur.

Une fois que l’utilisateur a consenti aux autorisations pour votre application, votre application peut acquérir des jetons d’accès qui représentent l’autorisation de l’application d’accéder à une ressource dans une certaine capacité. Un jeton d’accès ne peut être utilisé que pour une seule ressource. Mais encodé à l’intérieur du jeton d’accès est toutes les autorisations accordées à votre application pour cette ressource. Pour acquérir un jeton d’accès, votre application peut effectuer une demande au point de terminaison de jeton de la plateforme d'identité de Microsoft, comme suit :

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

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Vous pouvez utiliser le jeton d’accès résultant dans les requêtes HTTP à la ressource. Il indique de manière fiable à la ressource que votre application dispose de l’autorisation appropriée pour effectuer une tâche spécifique.

Pour plus d’informations sur le protocole OAuth 2.0 et sur la façon d’obtenir des jetons d’accès, consultez la référence du protocole de point de terminaison de la plateforme d’identités Microsoft.

Contenu connexe