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

Article
12/29/2023

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

Si vous avez besoin d’un accès programmatique Microsoft Defender pour le 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 d’introduction.

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 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 OAuth 2.0 Flux du code d’autorisation.

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

Créer un proxy d’application Microsoft Entra
Obtenir un jeton d’accès à l’aide de cette application
Utiliser le jeton pour accéder à l’API Defender for Cloud Apps

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 à l’API de Microsoft Defender for Cloud Apps pour le compte d’un utilisateur, vous aurez besoin de l’autorisation d’application correcte et de l’autorisation de l’utilisateur. 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 disposez de l’autorisation d’effectuer une action dans le portail, vous disposez de l’autorisation d’effectuer l’action dans l’API.

Créer une application

Connectez-vous sur Azure avec un compte utilisateur ayant le rôle d’Administrateur général.
Accédez à Microsoft Entra ID>Enregistrements App>Nouvel enregistrement.

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

Nom : saisissez un nom d’application cohérent qui s’affichera pour les utilisateurs de l’application.

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

Types de compte 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 annuaire. Cette option est mappée à Microsoft Entra-only à un seul locataire. Il s’agit de l’option par défaut, à moins que vous n’inscriviez l’application hors d’un répertoire. Dans les cas où l’application est inscrite hors d’un répertoire, l’option par défaut est multi-locataire Microsoft Entra et comptes Microsoft personnels.
Comptes dans un annuaire organisationnel	Sélectionnez cette option si vous voulez cibler tous les clients professionnels ou du domaine éducatif. Cette option est mappée à un multilocataire Microsoft Entra uniquement. Si vous avez inscrit l’application comme compte monolocataire Microsoft Entra-only, vous pouvez le mettre à jour avec un compte multilocataire Microsoft Entra et inversement par le biais du volet Authentification.
Comptes dans un annuaire organisationnel et comptes personnels Microsoft	Sélectionnez cette option pour cibler le plus grand nombre de clients. Cette option correspond aux comptes Microsoft Entra multi-locataires et personnels Microsoft. Si vous avez inscrit l’application en tant que comptes Microsoft personnels et Microsoft Entra multi-locataires, vous ne pouvez pas modifier cela dans l’interface utilisateur. Au lieu de cela, vous devez utiliser l’éditeur de manifeste d’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 et bureau), puis entrez l’URI de redirection (ou URL de réponse).
- Pour les applications web, indiquez l’URL de base de votre application. Par exemple, http://localhost:31544 peut être l’URL pour 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 de client public, indiquez l’URI utilisé par Microsoft Entra ID pour retourner les réponses de jeton. Entrez une valeur spécifique de votre application, par exemple, myapp://auth.
Pour voir des exemples spécifiques pour les applications web ou natives, consultez les Guides de démarrage rapides.

Lorsque vous avez terminé, sélectionnez Inscrire.

Autoriser votre application à accéder à Microsoft Defender for Cloud Apps et lui attribuer l’autorisation « Lire les alertes » :
- Dans la page de votre application, sélectionnez Autorisations API>Ajouter permission>API que mon organisation utilise> type 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.
- Choisissez Autorisations déléguées>Investigation.Read> sélectionnez Ajouter autorisations
- Remarque importante : Sélectionnez 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.
- 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.
Notez votre ID application et votre ID client :
- Dans la page de votre application, accédez à Vue d’ensemble et copiez les informations suivantes :

É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 pas 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 bloc	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 de Microsoft Entra, consultez le Tutoriel Microsoft Entra

Utilisation de C#

Copiez/collez la classe suivante dans votre application.

Utilisez la méthode AcquireUserTokenAsync avec votre ID application, l’ID client, le nom d’utilisateur et le mot de passe pour acquérir un jeton.

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 obtenu un jeton correct :

Copier/coller 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 :

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

Sélectionnez l’API que vous souhaitez utiliser. Pour plus d’informations, consultez API Defender for Cloud Apps.
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)
L’heure 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