Autorisation et API de sécurité Microsoft Graph

Les données de sécurité accessibles via l’API de sécurité Microsoft Graph sont sensibles et protégées par les autorisations et les rôles d’Azure Active Directory (Azure AD).

L’API de sécurité Microsoft Graph prend en charge deux types d’autorisation :

  • Autorisation au niveau application : aucun utilisateur n’est connecté (par exemple, un scénario SIEM). Les autorisations accordées à l’application déterminent l’autorisation.

    Remarque : Cette option peut prendre également en charge les cas où le contrôle d’accès basé sur les rôles (RBAC) est géré par l’application.

  • Autorisation déléguée par l'utilisateur : un utilisateur qui est membre du client Azure AD est connecté. L’utilisateur doit être membre d’un rôle d’administrateur Azure AD limité : soit lecteur sécurité soit administrateur de la sécurité ; en plus de l'application ayant reçu les autorisations requises.

Si vous appelez l’API de sécurité Microsoft Graph à partir de l’Afficheur Graph :

  • L’administrateur du client Azure AD doit donner explicitement l’autorisation d’accès pour les autorisations demandées pour l’application Afficheur Graph.
  • L’utilisateur doit être membre du rôle d’administrateur limité lecteur sécurité dans Azure AD (soit lecteur sécurité ou administrateur de la sécurité).

Remarque: l’Afficheur Graph ne prend pas en charge l'autorisation au niveau de l'application.

Si vous appelez l’API de sécurité Microsoft Graph à partir d’une application personnalisée ou de votre propre application :

  • L’administrateur du client Azure AD doit donner explicitement l’autorisation d’accès à votre application. Ceci est requis à la fois pour l'autorisation au niveau de l'application et pour l'autorisation déléguée par l'utilisateur.
  • Si vous utilisez une autorisation déléguée par l'utilisateur, l’utilisateur doit être membre du rôle de lecteur sécurité ou administrateur limité de sécurité administrateur dans Azure AD.

Gérer l'autorisation dans les applications client de l’API de sécurité

Les données de sécurité fournies via l’API de sécurité Microsoft Graph sont sensibles et doivent être protégées par des mécanismes appropriés d’authentification et d’autorisation. Le tableau suivant répertorie les étapes pour vous inscrire et créer une application cliente ayant accès à l’API de sécurité Microsoft Graph.

Qui Action
Développeur d'application ou propriétaire Inscrire l'application en tant qu'application d'entreprise.
Administrateur client Accorder des autorisations à l'application.
Administrateur client Attribuer des rôles aux utilisateurs.
Développeur d’applications Se connecter en tant qu’utilisateur et utiliser l’application pour accéder à l’API de sécurité Microsoft Graph.

L'enregistrement de l'application définit uniquement les autorisations dont l'application a besoin pour s'exécuter. Il n’accorde PAS ces autorisations à l’application.

L’administrateur client Azure AD DOIT accorder explicitement les autorisations à l'application. Cela doit être fait par client et doit être effectué chaque fois que les autorisations d’application sont modifiées dans le portail d’inscription de l’application.

Par exemple, supposons que vous ayez une application, deux clients Azure AD, T1 et T2 et deux autorisations P1 et P2. Voici le processus d’autorisation :

  • L’application enregistre pour demander la permission P1.
  • Lorsque les utilisateurs du client T1 obtiennent un jeton Azure AD pour cette application, le jeton ne contient aucune autorisation.
  • L’administrateur de client Azure AD T1 octroie explicitement des autorisations à l’application. Lorsque les utilisateurs du client T1 obtiennent un jeton Azure AD pour l’application, il contiendra l’autorisation P1.
  • Lorsque les utilisateurs du client T2 obtiennent un jeton Azure AD pour l’application, le jeton ne contient aucune autorisation ; étant donné que l’administrateur de client T2 n'a pas encore accordé d'autorisations à l'application. Une autorisation doit être accordée par client et par application.
  • L'application a son inscription modifiée pour exiger maintenant des autorisations P1 et P2.
  • Lorsque les utilisateurs du client T1 obtiennent un jeton Azure AD pour l’application, il contient uniquement l’autorisation P1. Les autorisations accordées à une application sont enregistrées en tant qu’instantanés de ce qui a été octroyé ; ils ne changent pas automatiquement après la modification de l'enregistrement de l'application (autorisation).
  • L’administrateur de client T2 octroie des autorisations P1 et P2 à l’application. Désormais, lorsque les utilisateurs du client T2 obtiennent un jeton Azure AD pour l’application, le jeton contiendra des autorisations P1 et P2.

Remarque: les jetons Azure AD pour l’application du client T1 et de l’application du client T2 contiennent des autorisations différentes, étant donné que chaque administrateur client a accordé des autorisations différentes à l’application.

  • Pour que l'application fonctionne à nouveau avec client T1, l’administrateur de client T1 doit autoriser explicitement les autorisations P1 et P2 à l’application.

Inscrire une application à l’aide du point de terminaison de la plateforme d’identités Microsoft

Pour inscrire une application au point de terminaison de la plateforme d’identités Microsoft, il vous faut :

  • Nom de l’application : une chaîne utilisée pour le nom de l’application.
  • Rediriger URL : l’URL où la réponse d’authentification Azure AD est envoyée. Pour commencer, vous pouvez utiliser la page d’accueil de test client web app.
  • Autorisations requises : les autorisations dont votre application a besoin pour pouvoir appeler Microsoft Graph.

Pour enregistrer votre application :

  1. Accédez au portail d’enregistrement des applications Azure et connectez-vous.

    Remarque: Vous n'êtes pas obligé d'être administrateur client. Vous serez redirigé vers la liste mes applications.

  2. Sélectionnez Nouvelle inscription.

  3. Sur la page d’inscription de la nouvelle application, saisissez une valeur pour Nom et sélectionnez les types de comptes que vous voulez prendre en charge. Dans le champ URI redirigée, entrez l’URL de redirection.

  4. Sélectionnez Enregistrer pour créer l’application et afficher sa page de présentation. *

  5. Accéder à la page de l’application Autorisations de l’API.

  6. Sélectionnez Ajouter une autorisation, puis sélectionnez Microsoft Graph dans le menu volant. Sélectionnez Autorisations déléguées. Utilisez la zone de recherche pour rechercher et sélectionner les autorisations requises. Pour obtenir la liste des autorisations, reportez-vous aux autorisations de sécurité.

    Remarque : l’API Microsoft Graph Security nécessite l’étendue *.Read.All pour les requêtes GET et l’étendue *.ReadWrite.All pour les requêtes PATCH/POST/DELETE.

    Autorisation Entité Demandes prises en charge
    SecurityActions.Read.All securityActions (aperçu) GET
    SecurityActions.ReadWrite.All securityActions (aperçu) GET, POST
    SecurityEvents.Read.All alerts
    secureScores
    secureScoreControlProfiles
    GET
    SecurityEvents.ReadWrite.All alerts
    secureScores
    secureScoreControlProfiles
    GET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedBy tiIndicator (aperçu) GET, POST, PATCH, DELETE
  7. Sélectionnez Ajouter des autorisations.

Enregistrez les informations suivantes :

  • ID de l’application (client)
  • URL de redirection
  • Liste des autorisations requises

* La protection avancée contre les menaces Windows Defender (WDATP) requiert plus de rôles d’utilisateur que n’en requiert l’API Microsoft Graph Security. Par conséquent, seuls les utilisateurs possédant le rôle WDATP et le rôle de l’API Microsoft Graph Security peuvent avoir accès aux données WDATP. L’authentification de l’application uniquement n’est pas limitée par ce problème. Par conséquent, nous vous recommandons d’utiliser un jeton d’authentification de l’application uniquement.

Pour plus d’informations, voir Inscrire votre application sur la Plateforme d’identités Microsoft.

Accorder des autorisations pour une application

L'inscription de l'application ne définit que l'autorisation requise par l'application ; elle n'accorde pas ces autorisations à l'application. Un administrateur client Azure AD doit autoriser explicitement ces autorisations en effectuant un appel au point de terminaison de l'administrateur consentant. Pour plus d’informations, voir utiliser le point de terminaison consenti de l'administrateur..

Pour accorder des autorisations pour une application, vous devez :

  • ID de l’application : l’ID de l’application à partir du portail d’enregistrement des applications Azure.
  • Rediriger l’URL : la chaîne que vous avez définie dans le portail d'enregistrement des applications Azure pour la réponse d'authentification.

Pour accorder les autorisations :

  • Dans un éditeur de texte, créez la chaîne d'URL suivante :

    https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL>

  • Dans un navigateur web, accédez à cette URL et connectez-vous en tant qu’administrateur client. La boîte de dialogue affiche la liste des autorisations requises par l'application, comme indiqué dans le portail d'enregistrement des applications. Sélectionnez OK pour accorder ces autorisations à l’application.

Remarque : Cette étape accorde des autorisations à l’application ; pas aux utilisateurs. Cela signifie que tous les utilisateurs appartenant au client Azure AD qui utilisent cette application recevront ces autorisations, même aux utilisateurs non administrateurs.

Attribuer des rôles d’Azure AD aux utilisateurs

Une fois qu’une application a reçu les permissions, chaque personne y ayant accès (c’est-à-dire les membres du client Azure AD) obtient une autorisation. Pour protéger davantage les données de sécurité sensibles, l’API de sécurité Microsoft Graph exige que le rôle Lecteur Sécurité Azure AD soit attribué aux utilisateurs. Pour plus d’informations, consultez Autorisations de rôle d’administrateur dans Azure Active Directory et Attribuer des rôles d’administrateur et de non-administrateur aux utilisateurs de Azure Active Directory.

Remarque : vous devez être un administrateur client pour effectuer cette étape.

Assigner un rôle à un utilisateur :

  1. Connectez-vous au Portail Microsoft Azure (https://portal.azure.com).
  2. Cliquez sur l’icône en haut à gauche pour afficher le menu du portail Azure. Sélectionnez les utilisateurs de Azure Active Directory > .
  3. Sélectionnez le nom d’utilisateur.
  4. Sélectionnez les rôles attribués, puis Ajouter une affectation.
  5. Sélectionnez Lecteur de sécurité, puis cliquez sur Ajouter.

Créer un code d’authentification

Pour créer un code d’authentification, vous devez :

  • ID de l’application : l’ID de l’application à partir du portail de l’enregistrement d’application.
  • Rediriger URL : l’URL où la réponse d’authentification Azure AD est envoyée. Pour commencer, vous pouvez utiliser https://localhost ou la page d’accueil de test client web app.
  • Touche application (facultatif) : la touche de l’application. Cela s'applique lorsque vous développez une application qui utilisera du code d'authentification uniquement pour l'application (c'est-à-dire ne prendra pas en charge l'authentification déléguée par l'utilisateur).

Le tableau suivant répertorie les ressources que vous pouvez utiliser pour créer un code d’authentification.

Type d’application Bibliothèque d’authentification
Applications de bureau : iOS MSAL.framework : Aperçu de bibliothèque d’authentification Microsoft pour iOS
Applications de bureau : Android Bibliothèque d’authentification de Microsoft (MSAL)
Applications de bureau : .Net Bibliothèque d’authentification de Microsoft (MSAL)
Applications Web : JavaScript SPA Bibliothèque d’authentification Microsoft pour aperçu JavaScript
Applications Web : serveur Web .NET OpenIdConnection, Cookies, SystemWeb
Applications Web : NodeJS application Web

Pour les applications qui n’utilisent pas des bibliothèques existantes, voir accéder au nom d’un utilisateur.

  1. Obtenir un code à partir d’Azure AD. La requête à appeler contient un paramètre pour l'ID d'application, l'URL de redirection et les autorisations requises.
  2. Utilisez le code pour obtenir un jeton d’accès.

Si vous utilisez la bibliothèque OpenId Connect, voir S’authentifier à l’aide d’Azure AD et OpenID Connect et appelez app.UseOpenIdConnectAuthentication().

Remarque : Si vous demandez des jetons d'authentification délégués par l'utilisateur, le paramètre de la bibliothèque est Étendues demandées. Utilisez User.Read pour ce paramètre au lieu de ce dont a besoin l'application enregistrée. Le paramètre d’étendues demandées n’affecte pas les autorisations contenues dans les jetons d’authentification renvoyés. Ceux-ci sont déterminés par les autorisations que l'administrateur du client a accordées à l'application.

Par exemple, si vous utilisez la bibliothèque .NET MSAL, appelez comme suit :

var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken;

Remarque : Cet exemple doit utiliser des autorisations moins privilégiées, par exemple, User.Read. Toutefois, le jeton d'accès renvoyé peut contenir des autorisations qui ont été accordées par l’administrateur client pour le client utilisateur actuel, par exemple, User.Read.All ou User.ReadWrite.All.

Un jeton (chaîne) est renvoyé par Azure AD contenant vos informations d’authentification et les autorisations requises par l’application. Affectez ce jeton à l’en-tête HTTP comme un jeton porteur, comme illustré dans l’exemple suivant.

request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken);

Microsoft Graph validera les informations contenues dans ce jeton et accordera ou refusera l’accès.

Pour afficher les revendications contenues dans le jeton retourné, utilisez la bibliothèque NuGet System.IdentityModel.Tokens.Jwt.

JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken;

La réponse de Microsoft Graph contient un en-tête appelé client-demande-id, qui est un GUID. Si l’accès est refusé, veuillez indiquer ce GUID lorsque vous demandez de l’aide à Microsoft Tech Community, pour vous aider à identifier la cause de ce problème d’authentification.