Partager via

Accéder à l’API Microsoft Defender for Cloud Apps avec le contexte utilisateur

  • Article

Cette page explique comment créer une application pour obtenir l’accès programmatique à Defender for Cloud Apps pour le compte d’un utilisateur.

Si vous avez besoin d’un accès par programmation Microsoft Defender for Cloud Apps sans utilisateur, reportez-vous à Access Microsoft Defender for Cloud Apps avec le contexte de l’application.

Si vous n’êtes pas sûr de l’accès dont vous avez besoin, lisez la page Introduction.

Microsoft Defender for Cloud Apps expose la plupart 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 en fonction des fonctionnalités Microsoft Defender for Cloud Apps. 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éer une application Microsoft Entra
  • Obtenir un jeton d’accès à l’aide de cette application
  • Utiliser le jeton pour accéder à Defender for Cloud Apps’API

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

Remarque

Lorsque vous accédez à Microsoft Defender for Cloud Apps’API pour le compte d’un utilisateur, vous avez besoin de l’autorisation d’application et de l’autorisation utilisateur appropriées. Si vous n’êtes pas familiarisé avec les autorisations utilisateur sur Microsoft Defender for Cloud Apps, consultez Gérer l’accès administrateur.

Conseil

Si vous avez l’autorisation d’effectuer une action dans le portail, vous avez l’autorisation d’effectuer l’action dans l’API.

Créer une application

  1. Dans le centre d’administration Microsoft Entra, inscrivez une nouvelle application. Pour plus d’informations, consultez Démarrage rapide : Inscrire une application avec le centre d’administration Microsoft Entra.

  2. Lorsque la page Inscrire une application s’affiche, saisissez les informations d’inscription de votre application :

    • Nom : entrez un nom d’application explicite qui s’affiche pour les utilisateurs de l’application.

    • Types de compte pris en charge : sélectionnez les comptes à prendre en charge par l’application.

      Types de comptes pris en charge Description
      Comptes dans cet annuaire organisationnel uniquement Sélectionnez cette option si vous générez une application métier. Cette option n’est pas disponible si vous n’inscrivez pas l’application dans un répertoire.

      Cette option correspond à Microsoft Entra monolocataire uniquement.

      Il s’agit de l’option par défaut, sauf si vous inscrivez l’application hors d’un annuaire. Dans les cas où l’application est inscrite en dehors d’un répertoire, la valeur par défaut est Microsoft Entra comptes Microsoft multilocataires et personnels.
      Comptes dans un annuaire organisationnel Sélectionnez cette option si vous souhaitez cibler tous les clients professionnels et éducatifs.

      Cette option correspond à un multilocataire Microsoft Entra uniquement.

      Si vous avez inscrit l’application comme Microsoft Entra monolocataire uniquement, vous pouvez la mettre à jour pour qu’elle soit Microsoft Entra multilocataire et revenir à un seul locataire via le volet Authentification.
      Comptes dans un annuaire organisationnel et comptes personnels Microsoft Sélectionnez cette option pour cibler l’ensemble le plus large de clients.

      Cette option correspond à Microsoft Entra comptes Microsoft multilocataires et personnels.

      Si vous avez inscrit l’application en tant que Microsoft Entra comptes Microsoft multilocataires et personnels, vous ne pouvez pas le modifier dans l’interface utilisateur. Vous devez utiliser l’éditeur de manifeste de l’application pour modifier les types de compte pris en charge.

    • URI de redirection (facultatif) : sélectionnez le type d’application que vous créez, **Web ou Client public (mobile & bureau), puis entrez l’URI de redirection (ou l’URL de réponse) de votre application.

      • Pour les applications web, indiquez l’URL de base de votre application. Par exemple, http://localhost:31544 peut être l’URL d’une application web en cours d’exécution sur votre ordinateur local. Les utilisateurs peuvent utiliser cette URL pour se connecter à une application web cliente.
      • Pour les applications clientes publiques, fournissez l’URI utilisé par Microsoft Entra ID pour retourner des réponses de jeton. Entrez une valeur spécifique de votre application, par exemple, myapp://auth.

      Pour accéder à des exemples spécifiques aux applications web ou natives, consultez les Guides de démarrage rapides.

      Lorsque vous avez terminé, sélectionnez Inscrire.

  3. Autorisez votre application à accéder à Microsoft Defender for Cloud Apps et attribuez-lui l’autorisation « Lire les alertes » :

    • Dans la page de votre application, sélectionnez Api Autorisations> Ajouter des APId’autorisation>que mon organization utilise>, tapez Microsoft Sécurité des applications cloud, puis sélectionnez Microsoft Sécurité des applications cloud.

    • Remarque : Microsoft Sécurité des applications cloud 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’autorisations.

    • Choisissez Autorisations> déléguéesInvestigation.Lire>, sélectionnez Ajouter des autorisations.

      Capture d’écran de l’ajout d’autorisations d’application.

    • Remarque importante : sélectionnez les autorisations appropriées. Investigation.Read n’est qu’un exemple. Pour les 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.

    • Sélectionnez Accorder le consentement de l’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. Notez votre ID d’application et votre ID de locataire :

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

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

É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 de la fermeture des alertes.
Afficher les plages d’adresses IP, mais pas ajouter, mettre à jour ou supprimer.

Effectuer toutes les actions d’entités.		 Liste des activités, extraction, commentaires
Liste des alertes, extraction, marquage comme lu/non lu
Liste des 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 lu/non lu, fermer
Liste des entités, extraction, arborescence d’extraction
Liste des sous-réseaux, créer/mettre à jour/supprimer
Discovery.read Effectuez toutes les actions prises en charge sur les activités et les alertes, à l’exception de la fermeture des alertes.
Répertorier les rapports de découverte et les catégories.		 Liste des alertes, extraction, marquage comme lu/non lu
Rapports de liste de découverte, catégories de rapports de liste
Discovery.manage Autorisations Discovery.read
Fermer les alertes, charger des fichiers de découverte et générer des scripts de bloc		 Liste des alertes, extraction, marquer comme lu/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épertorier et gérer les plages d’adresses IP. Liste des sous-réseaux, créer/mettre à jour/supprimer

Obtenir un jeton d’accès

Pour plus d’informations sur les jetons Microsoft Entra, consultez Microsoft Entra tutoriel

Utilisation de C#

  • Copiez/collez la classe suivante dans votre application.
  • Utilisez la méthode AcquireUserTokenAsync avec l’ID d’application, l’ID de locataire et l’authentification acquérir un jeton.

Remarque

Bien que l’exemple de code suivant montre comment acquérir un jeton à l’aide du flux de nom d’utilisateur et de mot de passe, Microsoft vous recommande d’utiliser des flux d’authentification plus sécurisés dans un environnement de production.

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class MDAUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

Valider le jeton

Vérifiez que vous avez 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 « scp » avec les autorisations d’application souhaitées

  • Dans la capture d’écran ci-dessous, vous pouvez voir un jeton décodé acquis à partir de l’application dans le tutoriel :

    Capture d’écran de la validation du jeton.

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

  • Choisissez l’API que vous souhaitez utiliser. Pour plus d’informations, consultez API Defender for Cloud Apps.

  • Définissez l’en-tête Authorization dans la requête HTTP que vous envoyez au « Porteur {token} » (le porteur est le schéma d’autorisation)

  • Le délai d’expiration du jeton est de 1 heure (vous pouvez envoyer plusieurs requêtes avec le même jeton)

  • 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://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