Partager via

Accès aux partenaires via les API Microsoft Defender pour point de terminaison

  • Article

S’applique à :

Importante

Les fonctionnalités de chasse avancées ne sont pas incluses dans Defender for Business.

Vous voulez découvrir Microsoft Defender pour point de terminaison ? Inscrivez-vous pour bénéficier d’un essai gratuit.

Remarque

Si vous êtes un client du gouvernement des États-Unis, utilisez les URI répertoriés dans Microsoft Defender pour point de terminaison pour les clients du gouvernement des États-Unis.

Conseil

Pour de meilleures performances, vous pouvez utiliser le serveur plus près de votre emplacement géographique :

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com
  • ina.api.security.microsoft.com

Cette page explique comment créer une application Microsoft Entra pour obtenir l’accès programmatique à Microsoft Defender pour point de terminaison pour le compte de vos clients.

Microsoft Defender pour point de terminaison expose la plupart de ses données et actions via un ensemble d’API programmatiques. Ces API vous aident à automatiser les flux de travail et à innover en fonction des fonctionnalités Microsoft Defender pour point de terminaison. L’accès à l’API nécessite l’authentification OAuth2.0. Pour plus d’informations, consultez Flux de code d’autorisation OAuth 2.0.

En général, vous devez effectuer les étapes suivantes pour utiliser les API :

  1. Créez une application Microsoft Entra multilocataire.

  2. Obtenez le consentement de votre administrateur client pour que votre application accède aux ressources Defender pour point de terminaison dont elle a besoin.

  3. Obtenez un jeton d’accès à l’aide de cette application.

  4. Utilisez le jeton pour accéder à Microsoft Defender pour point de terminaison’API.

Les étapes suivantes vous guident pour créer une application Microsoft Entra, obtenir un jeton d’accès pour Microsoft Defender pour point de terminaison et valider le jeton.

Importante

Microsoft vous recommande d’utiliser des rôles disposant du moins d’autorisations. Cela contribue à renforcer la sécurité de votre organisation. Le rôle d’administrateur général dispose de privilèges élevés. Il doit être limité aux scénarios d’urgence lorsque vous ne pouvez pas utiliser un rôle existant.

Créer l’application multilocataire

  1. Connectez-vous à votre locataire Azure.

  2. Accédez à Microsoft Entra ID>inscriptions d'applications>Nouvelle inscription.

    Volet de navigation vers l’inscription de l’application

  3. Dans le formulaire d’inscription :

    • Choisissez un nom pour votre application.

    • Types de comptes pris en charge : comptes dans n’importe quel annuaire organisationnel.

    • URI de redirection : type : Web, URI : https://portal.azure.com

      Page d’inscription de l’application partenaire Microsoft Azure

  4. Autorisez votre application à accéder à Microsoft Defender pour point de terminaison et attribuez-la avec le jeu minimal d’autorisations requis pour terminer l’intégration.

    • Dans la page de votre application, sélectionnez Api Autorisations> Ajouter des API d’autorisation>que mon organization utilise> le type WindowsDefenderATP, puis sélectionnez WindowsDefenderATP.

    • WindowsDefenderATP n’apparaît pas dans la liste d’origine. Commencez à écrire son nom dans la zone de texte pour le voir apparaître.

      L’option Ajouter une autorisation

Demander des autorisations d’API

Pour déterminer l’autorisation dont vous avez besoin, consultez la section Autorisations dans l’API que vous souhaitez appeler. Par exemple :

Dans l’exemple suivant, nous utilisons l’autorisation Lire toutes les alertes :

  1. Choisissez Autorisations d’application>Alert.Read.All> sélectionnez Ajouter des autorisations.

    Option qui permet d’ajouter une autorisation

  2. Sélectionnez Accorder le consentement

    • Chaque fois que vous ajoutez une autorisation, vous devez sélectionner Accorder le consentement pour que la nouvelle autorisation prenne effet.

    Option qui permet d’accorder le consentement

  3. Ajoutez un secret à l’application.

    • Sélectionnez Certificats & secrets, ajoutez une description au secret, puis sélectionnez Ajouter.

    Après avoir sélectionné Ajouter, veillez à copier la valeur du secret généré. Vous ne pourrez pas le récupérer après votre départ !

    La clé de création d’application

  4. Notez votre ID d’application :

    • Dans la page de votre application, accédez à Vue d’ensemble et copiez les informations suivantes :

      ID de création de l’application

  5. Ajoutez l’application au locataire de votre client.

    Vous devez que votre application soit approuvée dans chaque locataire client où vous envisagez de l’utiliser. Cette approbation est nécessaire, car votre application interagit avec Microsoft Defender pour point de terminaison’application pour le compte de votre client.

    Un compte d’utilisateur disposant des autorisations appropriées pour le locataire de votre client doit sélectionner le lien de consentement et approuver votre application.

    Le lien de consentement se présente sous la forme suivante :

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true

    Où 00000000-0000-0000-0000-000000000000 doit être remplacé par votre ID d’application.

    Après avoir sélectionné le lien de consentement, connectez-vous au locataire du client, puis accordez le consentement pour l’application.

    Bouton Accepter

    En outre, vous devez demander à votre client son ID de locataire et l’enregistrer pour une utilisation ultérieure lors de l’acquisition du jeton.

  6. Terminé ! Vous avez correctement inscrit une application ! Consultez les exemples suivants pour l’acquisition et la validation de jetons.

Obtenir un exemple de jeton d’accès

Pour obtenir un jeton d’accès au nom de votre client, utilisez l’ID de locataire du client sur les acquisitions de jeton suivantes.

Pour plus d’informations sur Microsoft Entra jeton, consultez Microsoft Entra tutoriel.

Utiliser PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

Utilisation de C#

Importante

Le package NuGet Microsoft.IdentityModel.Clients.ActiveDirectory et la bibliothèque Azure AD Authentication (ADAL) ont été déconseillés. Aucune nouvelle fonctionnalité n’a été ajoutée depuis le 30 juin 2020. Pour effectuer une mise à niveau, consultez le guide de migration.

  1. Créez une application console.

  2. Installez NuGet Microsoft.Identity.Client.

  3. Ajoutez le code suivant :

     using Microsoft.Identity.Client;

    Ce code a été testé avec NuGet Microsoft.Identity.Client.

  4. Copiez/collez le code suivant dans votre application (n’oubliez pas de mettre à jour les trois variables : tenantId, appIdet appSecret).

    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
const string authority = https://login.microsoftonline.com;
const string audience = https://api.securitycenter.microsoft.com;

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List<string> scopes = new List<string>() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

Utilisation de Python

Consultez Obtenir un jeton à l’aide de Python.

Utilisation de Curl

Remarque

La procédure suivante, supposée Curl pour Windows, est déjà installée sur votre ordinateur

  1. Ouvrez une fenêtre de commande.

  2. Définissez sur CLIENT_ID votre ID d’application Azure.

  3. Définissez sur CLIENT_SECRET votre secret d’application Azure.

  4. Définissez TENANT_ID sur l’ID de locataire Azure du client qui souhaite utiliser votre application pour accéder à Microsoft Defender pour point de terminaison application.

  5. Exécutez la commande suivante :

    curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

    Vous obtenez une réponse qui ressemble à l’extrait de code suivant :

    {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Valider le jeton

Vérifiez que vous avez reçu un jeton correct.

  1. Copiez/collez dans JWT le jeton que vous avez obtenu à l’étape précédente afin de le décoder.

  2. Vérifiez que vous obtenez une revendication de rôles avec les autorisations appropriées.

    Dans la capture d’écran suivante, vous pouvez voir un jeton décodé acquis à partir d’une application avec plusieurs autorisations pour Microsoft Defender pour point de terminaison :

    Page de validation de jeton

    La revendication « tid » est l’ID de locataire auquel appartient le jeton.

Utiliser le jeton pour accéder à Microsoft Defender pour point de terminaison’API

  1. Choisissez l’API que vous souhaitez utiliser. Pour plus d’informations, consultez API Microsoft Defender pour point de terminaison prises en charge.

  2. Définissez l’en-tête Authorization dans la requête HTTP à Bearer {token} laquelle vous envoyez (le porteur est le schéma d’autorisation). Le délai d’expiration du jeton est d’une heure (vous pouvez envoyer plusieurs requêtes avec le même jeton).

    Voici un exemple d’envoi d’une demande pour obtenir une liste d’alertes à l’aide de C# :

    var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

 // Do something useful with the response

Voir aussi

Conseil

Voulez-vous en savoir plus ? Engage avec la communauté Microsoft Security dans notre communauté technique : Microsoft Defender pour point de terminaison Tech Community.