Consentement administrateur sur la plateforme d’identités Microsoft

  • Article

Certaines autorisations requièrent le consentement d’un administrateur pour pouvoir être accordées au sein d’un locataire. Vous pouvez également utiliser le point de terminaison de consentement administrateur pour accorder des autorisations à un locataire entier.

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 faire partie du flux d’inscription de l’application, des paramètres de l’application, ou ce peut être 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 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 cela n’est pas strictement nécessaire, cela peut vous aider à créer une expérience plus intuitive pour les utilisateurs de l’organisation.

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.

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
        ?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
        &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
        &redirect_uri=http://localhost/myapp/permissions
        &state=12345
Paramètre Condition Description
tenant Obligatoire Le client d’annuaire auquel vous souhaitez demander l’autorisation. Peut être fourni au format GUID ou sous forme de nom convivial OU référencé de manière générique avec organizations comme indiqué dans l’exemple. N’utilisez pas « common », car les comptes personnels ne peuvent pas fournir le consentement de l’administrateur, sauf dans le contexte d’un locataire. Pour garantir une meilleure compatibilité avec les comptes personnels qui gèrent les locataires, utilisez l’ID de locataire, dans la mesure du possible.
client_id Requis L’ID d’application (client) que l’expérience Inscriptions d’applications du centre d’administration Microsoft Entra a attribué à votre application.
redirect_uri Requis 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. Il peut s’agir d’étendues statiques (utilisant /.default) ou dynamiques. Cela peut inclure les étendues OIDC (openid, profile, email).

À ce stade, Microsoft Entra ID nécessite qu’un administrateur client se connecte pour compléter la requête. 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 point de terminaison de consentement administrateur v1.0 et demande un consentement pour toutes les étendues trouvées dans les autorisations requises (utilisateur et application). Pour demander des autorisations d’application, vous devez utiliser la valeur /.default. Si vous ne souhaitez pas que les administrateurs voient une autorisation donnée dans l’écran de consentement administrateur quand vous utilisez /.default, la bonne pratique consiste à ne pas placer l’autorisation dans la section des autorisations requises. Au lieu de cela, vous pouvez utiliser le consentement dynamique pour ajouter les autorisations que vous souhaitez voir dans l’écran de consentement au moment de l’exécution, au lieu d’utiliser /.default.

Réponse correcte

Si l’administrateur approuve les autorisations pour votre application, la réponse correcte ressemble à ce qui suit :

http://localhost/myapp/permissions
    ?admin_consent=True
    &tenant=fa00d692-e9c7-4460-a743-29f2956fd429
    &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
    &state=12345
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é.
scope Ensemble d’autorisations auquel l’accès a été accordé pour l’application.
admin_consent Sera défini sur True.

Avertissement

N’utilisez jamais la valeur de l’ID de locataire du paramètre tenant pour authentifier ou autoriser des utilisateurs. La valeur de l’ID de locataire peut être mise à jour et envoyée par des intervenants malveillants pour emprunter l’identité d’une réponse à votre application. Cela peut entraîner l’exposition de votre application à des incidents de sécurité.

Réponse d’erreur

http://localhost/myapp/permissions
        ?admin_consent=True
        &error=consent_required
        &error_description=AADSTS65004%3a+The+resource+owner+or+authorization+server+denied+the+request.%0d%0aTrace+ID%3a+d320620c-3d56-42bc-bc45-4cdd85c41f00%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
        &state=12345

Ajout aux paramètres affichés dans une réponse correcte. Les paramètres d’erreur s’affichent comme ci-dessous.

Paramètre Description
error Une chaîne de code d’erreur pouvant être utilisée pour classer les types d’erreurs se produisant, et pouvant être utilisée pour intervenir face aux erreurs.
error_description Un message d’erreur spécifique qui peut aider un développeur à identifier la cause principale d’une erreur.
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 Aura la valeur True pour indiquer que cette réponse s’est produite sur un flux de consentement administrateur.

Étapes suivantes