Partager via

Accédez à Microsoft Defender for Cloud Apps avec le contexte de l’application

  • Article

Cette page décrit comment créer une application pour obtenir un accès programmatique à Defender for Cloud Apps sans un utilisateur. Si vous avez besoin d’un accès par programmation à Defender pour le cloud Apps pour le compte d’un utilisateur, consultez Obtenir l’accès avec le contexte utilisateur. Si vous n’êtes pas sûr de l’accès dont vous avez besoin, consultez la page Gestion des jetons d’API.

Microsoft Defender for Cloud Apps expose une grande partie de ses données et actions par le biais d’un ensemble d’API programmatiques. Ces API vous permettent d’automatiser les flux de travail et d’innover sur la base des fonctionnalités de Defender for Cloud Apps. L’accès à l’API nécessite l’authentification OAuth2.0. Pour plus d’informations, consultez OAuth 2.0 Flux du code d’autorisation.

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

  • Créez une application Microsoft Entra.
  • Obtenir un jeton d’accès à l’aide de cette application.
  • Utilisez le jeton pour accéder aux API de Defender for Cloud Apps.

Cet article explique comment créer une application Microsoft Entra, obtenir un jeton d’accès pour Microsoft Defender for Cloud Apps, et valider le jeton.

Créer une application pour Defender for Cloud Apps

  1. Dans le centre d’administration Microsoft Entra, enregistrez une nouvelle application. Pour plus d’informations, consultez Démarrage rapide : Enregistrer une application dans le centre d’administration Microsoft Entra.

  2. Pour permettre à votre application d’accéder à Defender pour le cloud Apps et de l’affecter à l’autorisation « Lire toutes les alertes », sur votre page d’application, sélectionnez API d’autorisation>Ajouter permission>API que mon organisation utilise>, saisissez Microsoft Cloud App Security, puis sélectionnez Microsoft Cloud App Security.

    Remarque

    Microsoft Cloud App Security n’apparaît pas dans la liste d’origine. Commencez à écrire son nom dans la zone de texte pour le voir apparaître. Veillez à taper ce nom, même si le produit est maintenant appelé Defender for Cloud Apps.

    Capture d’écran de l’ajout d’une autorisation.

    • Sélectionnez Autorisations de l’application>Investigation.Read, puis sélectionnez Ajouter autorisations.

      Capture d’écran de l’ajout d’une autorisation d’application.

      Vous devez sélectionner les autorisations appropriées. Investigation.Read n’est qu’un exemple. Pour d’autres étendues d’autorisation, consultez Étendues d’autorisation prises en charge

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

  3. Sélectionner Accorder le consentement administrateur.

    Remarque

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

    Capture d’écran de l’octroi d’autorisations d’administrateur.

  4. Pour ajouter un secret à l’application, sélectionnez Certificats et secrets, sélectionnez Nouveau secret client, ajoutez une description au secret, puis sélectionnez Ajouter.

    Remarque

    Après avoir sélectionné Ajouter, sélectionnez copier la valeur de secret générée. Vous ne pouvez récupérer cette valeur une fois que vous avez quitté ce panneau.

    Capture d’écran de la création d’une clé d’application.

  5. Notez votre ID application et votre ID client. Sur la page de votre application, accédez à Vue d’ensemble et copiez l’ID de l’application (client) et l’ID du répertoire (locataire).

    Capture d’écran de l'ID d'application créé.

  6. Seulement pour les partenaires Microsoft Defender for Cloud Apps. Définissez votre application sur multilocataire (disponible dans tous les locataires après le consentement). Cela est nécessaire pour les applications tierces (par exemple, si vous créez une application destinée à s’exécuter dans le locataire de plusieurs clients). Cela n’est pas obligatoire si vous créez un service que vous souhaitez exécuter uniquement dans votre locataire (par exemple, si vous créez une application pour votre propre utilisation qui interagira uniquement avec vos propres données). Pour définir votre application sur multilocataire :

    • Accédez à l’Authentification et ajoutez https://portal.azure.com en tant que URI de redirection.

    • En bas de la page, sous Types de compte pris en charge, sélectionnez le consentement d’application Comptes dans un annuaire organisationnel pour votre application multilocataire.

    Vous avez besoin que votre application soit approuvée dans chaque locataire où vous envisagez de l’utiliser. Cela est dû au fait que votre application interagit Defender for Cloud Apps pour le compte de votre client.

    Vous (ou votre client si vous écrivez une application tierce) devez sélectionner le lien de consentement et approuver votre application. Le consentement doit être effectué avec un utilisateur disposant de privilèges d’administration dans Active Directory.

    La formule est construite comme suit :

    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 est remplacé par votre ID d’application.

Vous avez terminé. Vous avez correctement inscrit une application ! Consultez les exemples ci-dessous pour l’acquisition et la validation de jetons.

Étendues d’autorisation prises en charge

Nom de l’autorisation Description Actions prises en charge
Investigation.read Effectuez toutes les actions prises en charge sur les activités et les alertes, à l’exception des alertes de fermeture.
Afficher les plages d’adresses IP, mais sans ajouter, mettre à jour ou supprimer.

Effectuez toutes les actions d’entités.		 Liste des activités, extraction, commentaires
Liste des alertes, extraction, marque comme lu/non lu
Liste d’entités, extraction, arborescence d’extraction
Liste des sous-réseaux
Investigation.manage Effectuez toutes les actions investigation.read en plus de la gestion des alertes et des plages d’adresses IP. Liste des activités, extraction, commentaires
Liste des alertes, extraction, marquer comme lus/non lu, fermer
Liste d’entités, extraction, arborescence d’extraction
Liste de sous-réseaux, création/mise à jour/suppression
Discovery.read Effectuez toutes les actions prises en charge sur les activités et les alertes, à l’exception des alertes de fermeture.
Répertorier les rapports et les catégories de découverte.		 Liste des alertes, extraction, marque comme lu/non lu
Rapports de liste de découverte, catégories de rapports de liste
Discovery.manage Autorisations Discovery.read
Fermer des alertes, charger des fichiers de découverte et générer des scripts de blocage		 Liste des alertes, extraction, marquer comme lus/non lu, fermer
Rapports de liste de découverte, catégories de rapports de liste
Chargement du fichier de découverte, génération d’un script de bloc
Settings.read Répertorier les plages d’adresses IP. Liste des sous-réseaux
Settings.manage Répertoriez et gérez les plages d’adresses IP. Liste de sous-réseaux, création/mise à jour/suppression

Obtention d’un jeton d’accès

Pour plus d’informations sur les jetons Microsoft Entra, consultez le Tutoriel Microsoft Entra.

Utiliser PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

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

$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$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

Utiliser C#

Le code suivant a été testé avec NuGet Microsoft.Identity.Client 4.47.2.

  1. Créez une application console.

  2. Installez NuGet Microsoft.Identity.Client.

  3. Ajoutez ce qui suit :

    using Microsoft.Identity.Client;

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

    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // 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 = "05a65629-4c1b-48c1-a78b-804c4abdd4af";

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

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

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

string token = authResult.AccessToken;

Utiliser Python

Consultez Bibliothèque d’authentification Microsoft (MSAL) pour Python.

Utiliser Curl

Remarque

La procédure suivante suppose que Curl pour Windows est déjà installé sur votre ordinateur.

  1. Ouvrez une invite de commandes et définissez CLIENT_ID sur votre ID d’application Azure.
  2. Définissez CLIENT_SECRET sur votre secret d’application Azure.
  3. Définissez TENANT_ID sur l’ID de locataire Azure du client qui souhaite utiliser votre application pour accéder à Defender pour le cloud Apps.
  4. 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=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Vous obtenez une réponse de la forme suivante :

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

Valider le jeton

Vérifiez que vous avez obtenu le jeton correct :

  1. Copiez et collez le jeton que vous avez obtenu à l’étape précédente dans JWT pour le décoder.
  2. Vérifiez que vous obtenez une revendication « rôles » avec les autorisations souhaitées
  3. Dans l’image suivante, vous pouvez voir un jeton décodé acquis à partir d’une application avec des autorisations pour tous les rôles Microsoft Defender for Cloud Apps :

Capture d'écran de la validation du jeton.

Utiliser le jeton pour accéder à l’API Microsoft Defender for Cloud Apps

  1. Sélectionnez l’API que vous souhaitez utiliser. Pour plus d’informations, consultez API de Defender for Cloud Apps.
  2. Définissez l’en-tête d’autorisation dans la requête http que vous envoyez à « Porteur {token} » (le porteur est le schéma d’autorisation).
  3. 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 requête pour obtenir une liste d’alertes en utilisant C# :

    var httpClient = new HttpClient();

    var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");

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

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

    // Do something useful with the response

Voir aussi