Demande d’autorisations par le biais d’un consentement

  • Article

Les applications de la plateforme d’identités Microsoft s’appuient sur le consentement pour accéder aux ressources ou aux 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 l’aidera à 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 par le biais du consentement.

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 dans le centre d’administration Microsoft Entra. 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 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 demandera toutes les autorisations dont elle pourrait avoir besoin à l’avance. Cela peut décourager les utilisateurs et les administrateurs d’approuver la demande d’accès de votre application.

Avec le point de terminaison de la plateforme d’identité Microsoft, vous pouvez ignorer les autorisations statiques définies dans les informations d’inscription d’une application dans le centre d’administration Microsoft Entra. Au lieu de cela, vous pouvez demander des autorisations de manière 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.

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

Dans l’exemple suivant, 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 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.

Capture d’écran montrant le consentement sur le compte professionnel.

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.

La demande de consentement pour un locataire entier nécessite le consentement de l’administrateur. 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.

Lorsque votre application demande des autorisations déléguées qui nécessitent le consentement de l’administrateur, l’utilisateur reçoit un message d’erreur indiquant qu’il n’est pas autorisé à donner son consentement aux autorisations de votre application. L’utilisateur doit demander à son administrateur l’accès à l’application. Si l’administrateur accorde le consentement pour l’ensemble du locataire, les utilisateurs de l’organisation ne voient pas de page de consentement pour l’application, sauf si les autorisations précédemment accordées sont révoquées ou que l’application demande une nouvelle autorisation de manière incrémentielle.

Les administrateurs qui utilisent la même application verront 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 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 le locataire. Lorsque votre application demande l’accès aux 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 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.

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 ressources est omis dans le paramètre d’étendue, la ressource est censée être Microsoft Graph. Par exemple, scope=User.Read est équivalent à 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 du consentement n’est pas effectué pour le compte d’un utilisateur spécifique. Au lieu de cela, l’application cliente reçoit directement des autorisations, 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 en amont et accorder le consentement de l’administrateur via le centre d’administration Microsoft Entra.

Si l’application qui demande l’autorisation est une application multilocataire, 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 au nom 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 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 pour une application avec les options suivantes.

En général, 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.
  • 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 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 le consentement de l’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 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 :

  1. Connectez-vous au Centre d’administration de Microsoft Entra au minimum en tant qu’Administrateur d’application cloud.
  2. Accédez à Identité>Applications>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 de l’API>Ajouter une autorisation.
  5. Sélectionnez Microsoft Graph dans la liste des API disponibles. Ajoutez ensuite les autorisations dont votre application a besoin.
  6. Sélectionnez Ajouter des autorisations.

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=aaaabbbb-0000-cccc-1111-dddd2222eeee&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.

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.

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

Voir aussi