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

Article
02/27/2024

S’applique à :

Importante

Les fonctionnalités de repérage avancées ne sont pas incluses dans Defender pour les entreprises.

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

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 :

Créez une application Microsoft Entra multilocataire.
Obtenez le consentement de votre administrateur client pour que votre application accède aux ressources Defender pour point de terminaison dont elle a besoin.
Obtenez un jeton d’accès à l’aide de cette application.
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.

Créer l’application multilocataire

Connectez-vous à votre locataire Azure avec l’utilisateur disposant du rôle Administrateur général .
Accédez à Microsoft Entra ID>inscriptions d'applications>Nouvelle inscription.
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
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.
- Notez que WindowsDefenderATP n’apparaît pas dans la liste d’origine. Commencez à écrire son nom dans la zone de texte pour le voir apparaître.

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 :

Pour exécuter des requêtes avancées, sélectionnez l’autorisation « Exécuter des requêtes avancées »
Pour isoler un appareil, sélectionnez l’autorisation « Isoler la machine »

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

Choisissez Autorisations d’application>Alert.Read.All> sélectionnez Ajouter des autorisations.
Sélectionnez Accorder le consentement
- Remarque : chaque fois que vous ajoutez une autorisation, vous devez sélectionner Accorder le consentement pour que la nouvelle autorisation prenne effet.
Ajoutez un secret à l’application.
- Sélectionnez Certificats & secrets, ajoutez une description au secret, puis sélectionnez Ajouter.
Important : 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 !
Notez votre ID d’application :
- Dans la page de votre application, accédez à Vue d’ensemble et copiez les informations suivantes :
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 utilisateur disposant d’un administrateur général du 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-00000-000000000 doit être remplacé par votre ID d’application

Après avoir cliqué sur le lien de consentement, connectez-vous avec l’administrateur général du locataire du client et donnez votre consentement à l’application.

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

Note: 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#

Le code ci-dessous a été testé avec Nuget Microsoft.Identity.Client

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. Nous vous encourageons vivement à effectuer une mise à niveau. Pour plus d’informations, consultez le guide de migration .

Créer une application console
Installer NuGet Microsoft.Identity.Client
Ajoutez les informations ci-dessous à l’aide de
```
using Microsoft.Identity.Client;
```

Copiez/collez le code ci-dessous 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

Reportez-vous à Obtenir un jeton à l’aide de Python.

Utilisation de Curl

Remarque

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

Ouvrez une fenêtre de commande.
Définissez CLIENT_ID sur votre ID d’application Azure.
Définissez CLIENT_SECRET à votre secret d’application Azure.
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.

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 du formulaire :

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

Copiez/collez dans JWT le jeton que vous avez obtenu à l’étape précédente afin de le décoder.
Vérifiez que vous obtenez une revendication « rôles » avec les autorisations souhaité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 :

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

Choisissez l’API que vous souhaitez utiliser. Pour plus d’informations, consultez API Microsoft Defender pour point de terminaison prises en charge.
Définissez l’en-tête Authorization dans la requête HTTP que vous envoyez à « Porteur {token} » (le porteur est le schéma d’autorisation). La durée d’expiration du jeton est de 1 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