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
Meld u aan bij Azure met een gebruikersaccount met de rol Global Beheer istrator.
Navigeer naar Azure Active Directory> App-registraties> Nieuwe registratie.
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.
- Geef voor webtoepassingen de basis-URL van de app op.
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.
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