Partager via

Guide du développeur relatif aux demandes d’autorisations et de consentement sur 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 de mieux réussir auprès des utilisateurs et des organisations.

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

Remarque

Pour les applications chez les locataires externes, les clients ne peuvent pas eux-mêmes consentir aux autorisations. Un administrateur devra accorder son consentement pour que l’application puisse accéder aux ressources en son nom. Pour plus d’informations, consultez Accorder le consentement de l’administrateur.

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’octroie pas 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 l’utilisation du consentement statique et d’une liste d’autorisations unique garde le code simple et agréable, cela signifie également que votre application demande toutes les autorisations dont elle pourrait avoir besoin à l’avance. Ce paramètre peut décourager 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 dynamiquement à partir du code de l’application. Vous pouvez commencer par demander un ensemble minimal d’autorisations au préalable et demander d’autres permissions au fil du temps, à mesure que le client utilise des fonctionnalités supplémentaires de l’application. Pour ce faire, vous pouvez spécifier les étendues dont votre application a besoin à tout moment en incluant les é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 n’a pas consenti à l’une des étendues de la demande, il obtient une invite à donner son consentement pour toutes les autorisations de cette demande. Ces autorisations seront accordées en plus des autres autorisations déjà accordées pour cette application (c’est-à-dire incrémentielles). Le consentement incrémentiel 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 anticipez l’expérience de consentement et demandez toutes les autorisations dans une même 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 de taille pour les autorisations qui nécessitent le consentement 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 recommandons à un développeur de répertorier toutes les autorisations d’administrateur dont l’application a besoin dans le portail.

Cela permet aux administrateurs d’abonnés 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 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 à donner son consentement.

Dans l’exemple suivant, les autorisations offline_access (« Conserver l’accès aux données auxquelles vous lui donnez 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 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 administrateur, les utilisateurs voient une erreur « non autorisés à donner leur consentement » et doivent demander un accès à un administrateur. Une fois qu’un administrateur donne le consentement pour l’ensemble de l’abonné, 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 qui utilisent la même application voient l’invite de consentement 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 Informations de référence sur les 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 l’abonné. 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 administrateur même si ce n’est pas nécessaire 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 valeurs par défaut des paramètres scope 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. 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. Les administrateurs doivent configurer les autorisations initialement et accorder le consentement de l’administrateur via le Centre d’administration Microsoft Entra.

Si l’application qui demande l’autorisation est une application multi-abonné, son inscription d’application existe uniquement dans l’abonné où elle a été créée. Par conséquent, les autorisations ne peuvent pas être configurées dans l’abonné 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 donner leur consentement à ces autorisations, les administrateurs doivent se connecter à l’application eux-mêmes, de sorte que l’expérience de connexion avec consentement administrateur est déclenchée. Pour découvrir comment configurer l’expérience de consentement administrateur pour les applications multi-abonnés, consultez Activer les connexions multi-abonnés.

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 :

  • Une partie du flux d’inscription de l’application.
  • 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 la connexion d’un utilisateur 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. Elles doivent être un sur-ensemble des autorisations que l’application demande de manière dynamique ou incrémentielle.

Remarque

Les autorisations d’application peuvent être demandées uniquement à l’aide de .default. 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 Client d’annuaire ayant accordé à votre application les autorisations demandées au format GUID.
state Une valeur incluse dans la demande renvoyée dans la réponse de 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 correcte du point de terminaison de consentement administrateur, votre application se voit octroyer les autorisations qu’elle avait 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. Toutefois, toutes les autorisations accordées à votre application pour cette ressource sont encodées dans le jeton d’accès. 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

  • Last updated on