Toegang tot Microsoft Defender voor Cloud Apps-API met gebruikerscontext

Notitie

Microsoft Defender voor Cloud Apps maakt nu deel uit van Microsoft Defender XDR, die signalen correleert vanuit de Microsoft Defender-suite en biedt detectie, onderzoek en krachtige responsmogelijkheden op incidentniveau. Zie Microsoft Defender voor Cloud Apps in Microsoft Defender XDR voor meer informatie.

Op deze pagina wordt beschreven hoe u een toepassing maakt om programmatische toegang te krijgen tot Defender voor Cloud Apps namens een gebruiker.

Als u programmatische toegang nodig hebt Microsoft Defender voor Cloud Apps zonder gebruiker, raadpleegt u Access Microsoft Defender voor Cloud Apps met toepassingscontext.

Als u niet zeker weet welke toegang u nodig hebt, leest u de introductiepagina.

Microsoft Defender voor Cloud Apps maakt veel van de gegevens en acties beschikbaar via een set programmatische API's. Met deze API's kunt u werkstromen automatiseren en innoveren op basis van Microsoft Defender voor Cloud Apps-mogelijkheden. Voor de API-toegang is OAuth2.0-verificatie vereist. Zie OAuth 2.0 Authorization Code Flow voor meer informatie.

Over het algemeen moet u de volgende stappen uitvoeren om de API's te gebruiken:

• Een Azure Active Directory-toepassing (Azure AD) maken
• Een toegangstoken ophalen met deze toepassing
• Het token gebruiken om toegang te krijgen tot Defender voor Cloud Apps-API

Op deze pagina wordt uitgelegd hoe u een Azure AD-toepassing maakt, een toegangstoken opvragen Microsoft Defender voor Cloud Apps en het token valideert.

Notitie

Wanneer u namens een gebruiker toegang krijgt tot Microsoft Defender voor Cloud Apps-API, hebt u de juiste toepassingsmachtiging en gebruikersmachtiging nodig. Zie Beheerderstoegang beheren als u niet bekend bent met gebruikersmachtigingen voor Microsoft Defender voor Cloud Apps.

Tip

Als u gemachtigd bent om een actie uit te voeren in de portal, hebt u de machtiging om de actie uit te voeren in de API.

Een app maken

1. Meld u aan bij Azure met een gebruikersaccount met de rol Global Beheer istrator.

2. Navigeer naar Azure Active Directory> App-registraties> Nieuwe registratie.

   

3. Wanneer de pagina Een toepassing registreren wordt weergegeven, voert u de registratiegegevens van uw toepassing in:

   • Naam: voer een beschrijvende toepassingsnaam in. Deze wordt zichtbaar voor gebruikers van de app.

   • Ondersteunde accounttypen: selecteer voor welke accounts de toepassing ondersteuning moet bieden.

     Ondersteunde rekeningtypen	Beschrijving
     Alleen accounts in deze organisatiemap	Selecteer deze optie als u een LOB-toepassing (Line-Of-Business) bouwt. Deze optie is niet beschikbaar als u de toepassing niet in een map registreert. Deze optie wordt alleen toegewezen aan Azure AD met één tenant. Dit is de standaardoptie tenzij u de app registreert buiten een map. In gevallen waarbij de app is geregistreerd buiten een map, is de standaardinstelling Azure AD met meerdere tenants en persoonlijke Microsoft-accounts.
     Accounts in elke organisatiemap	Selecteer deze optie als u alle zakelijke klanten en onderwijsinstellingen wilt bereiken. Deze optie wordt alleen toegewezen aan Azure AD met meerdere tenants. Als u de app hebt geregistreerd als slechts één tenant van Azure AD, kunt u deze bijwerken naar Azure AD met meerdere tenants en terug naar één tenant via het deelvenster Verificatie .
     Accounts in elke organisatiemap en persoonlijke Microsoft-accounts	Selecteer deze optie als u de breedste groep klanten wilt bereiken. Deze optie wordt toegewezen aan Azure AD met meerdere tenants en persoonlijke Microsoft-accounts. Als u de app hebt geregistreerd als Azure AD-accounts met meerdere tenants en persoonlijke Microsoft-accounts, kunt u deze niet wijzigen in de gebruikersinterface. In plaats daarvan moet u de Application Manifest Editor gebruiken om de ondersteunde rekeningtypen te wijzigen.

   • Omleidings-URI (optioneel): selecteer het type app dat u bouwt, web - of openbare client (mobiel & bureaublad) en voer vervolgens de omleidings-URI (of antwoord-URL) voor uw toepassing in.

     • Geef voor webtoepassingen de basis-URL van de app op. http://localhost:31544 kan bijvoorbeeld de URL zijn van een web-app die op uw lokale machine wordt uitgevoerd. Gebruikers moeten deze URL gebruiken om zich bij een webclienttoepassing aan te melden.
     • Geef voor openbare clienttoepassingen de URI op die in Azure Active Directory wordt gebruikt om tokenantwoorden te retourneren. Voer een waarde in die specifiek is voor de toepassing, zoals myapp://auth.

     Raadpleeg onze snelstarts om specifieke voorbeelden te zien van webtoepassingen of systeemeigen toepassingen.

     Selecteer Registreren wanneer u klaar bent.

4. Sta toe dat uw toepassing toegang heeft tot Microsoft Defender voor Cloud Apps en wijs deze machtiging Leeswaarschuwingen toe:

   • Selecteer op uw toepassingspagina API-machtigingen>toevoegen machtigings-API's>die mijn organisatie gebruikt> het type Microsoft Cloud App Security en selecteer vervolgens Microsoft Cloud App Security.

   • Opmerking: Microsoft Cloud App Security wordt niet weergegeven in de oorspronkelijke lijst. Begin met het schrijven van de naam in het tekstvak om deze weer te geven. Zorg ervoor dat u deze naam typt, ook al wordt het product nu Defender voor Cloud Apps genoemd.

     

   • Kies Gedelegeerde machtigingen>Investigation.Read> selecteer Machtigingen toevoegen

     

   • Belangrijke opmerking: selecteer de relevante machtigingen. Investigation.Read is slechts een voorbeeld. Zie Ondersteunde machtigingsbereiken voor andere machtigingsbereiken

     • Als u wilt bepalen welke machtiging u nodig hebt, bekijkt u de sectie Machtigingen in de API die u wilt aanroepen.

   • Selecteer Beheerderstoestemming verlenen

     Opmerking: Telkens wanneer u een machtiging toevoegt, moet u Beheerderstoestemming verlenen selecteren om de nieuwe machtiging van kracht te laten worden.

     

5. Noteer uw toepassings-id en uw tenant-id:

   • Ga op de toepassingspagina naar Overzicht en kopieer de volgende informatie:

     

Ondersteunde machtigingsbereiken

Machtigingnaam	Beschrijving	Ondersteunde acties
Investigation.read	Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen sluiten. IP-bereiken weergeven, maar niet toevoegen, bijwerken of verwijderen. Voer alle acties voor entiteiten uit.	Lijst met activiteiten, ophalen, feedback Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen Lijst met entiteiten, ophalen, ophalen, ophalen van structuur Subnetlijst
Investigation.manage	Voer alle investigation.read-acties uit naast het beheren van waarschuwingen en IP-bereiken.	Lijst met activiteiten, ophalen, feedback Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen, sluiten Lijst met entiteiten, ophalen, ophalen, ophalen van structuur Subnetlijst, maken/bijwerken/verwijderen
Discovery.read	Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen sluiten. Detectierapporten en -categorieën weergeven.	Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen Detectielijstrapporten, lijstrapportcategorieën
Discovery.manage	Discovery.read-machtigingen Waarschuwingen sluiten, detectiebestanden uploaden en blokscripts genereren	Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen, sluiten Detectielijstrapporten, lijstrapportcategorieën Detectiebestand uploaden, blokscript genereren
Instellingen.read	IP-bereiken weergeven.	Subnetlijst
Instellingen.manage	IP-bereiken weergeven en beheren.	Subnetlijst, maken/bijwerken/verwijderen

Een toegangstoken opvragen

Zie de zelfstudie over Azure AD voor meer informatie over Azure AD-tokens

C# gebruiken

• Kopieer/plak de volgende klasse in uw toepassing.

• Gebruik de methode AcquireUserTokenAsync met uw toepassings-id, tenant-id, gebruikersnaam en wachtwoord om een token te verkrijgen.

  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>();
                  }
              }
          }
      }
  } 
  

Het token valideren

Controleer of u een correct token hebt:

• Kopiëren/plakken in JWT het token dat u in de vorige stap hebt gekregen om het te decoderen

• Controleer of u een 'scp'-claim krijgt met de gewenste app-machtigingen

• In de onderstaande schermopname ziet u een gedecodeerd token dat is verkregen uit de app in de zelfstudie:

  

Het token gebruiken om toegang te krijgen tot de MICROSOFT DEFENDER VOOR CLOUD Apps-API

• Kies de API die u wilt gebruiken. Zie Defender voor Cloud Apps-API voor meer informatie.

• Stel de autorisatieheader in de HTTP-aanvraag in die u verzendt naar Bearer {token} (Bearer is het autorisatieschema)

• De verlooptijd van het token is 1 uur (u kunt meer dan één aanvraag met hetzelfde token verzenden)

• Voorbeeld van het verzenden van een aanvraag voor het ophalen van een lijst met waarschuwingen met behulp van 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
  

Zie ook

• API-tokens beheren
• Microsoft identity platform en OAuth 2.0-autorisatiecodestroom