Sovelluksen luominen kumppanin Microsoft Defender XDR ohjelmointirajapintoihin

Koskee seuraavia:

• Microsoft Defender XDR

Tärkeää

Jotkin tiedot liittyvät tuotteen ennakkoon, jota voidaan muuttaa huomattavasti ennen kaupallista julkaisua. Microsoft ei anna nimenomaisia eikä oletettuja takuita tässä annetuista tiedoista.

Tällä sivulla kuvataan, miten luodaan Microsoft Entra sovellus, jolla on ohjelmallinen käyttöoikeus Microsoft Defender XDR useiden vuokraajien käyttäjien puolesta. Usean vuokraajan sovellukset ovat hyödyllisiä suurten käyttäjäryhmien palvelemiseen.

Jos tarvitset Microsoft Defender XDR ohjelmallisen käyttöoikeuden yksittäisen käyttäjän puolesta, katso Sovelluksen luominen, jotta voit käyttää Microsoft Defender XDR ohjelmointirajapintoja käyttäjän puolesta. Jos tarvitset käyttöoikeuden ilman eksplisiittisesti määritettyä käyttäjää (esimerkiksi jos kirjoitat taustasovellusta tai daemonia), katso Sovelluksen luominen, jotta voit käyttää Microsoft Defender XDR ilman käyttäjää. Jos et ole varma, millaisen käyttöoikeuden tarvitset, katso Aloittaminen.

Microsoft Defender XDR paljastaa suuren osan tiedoistaan ja toiminnoistaan ohjelmallisten ohjelmointirajapintojen avulla. Näiden ohjelmointirajapintojen avulla voit automatisoida työnkulkuja ja hyödyntää Microsoft Defender XDR ominaisuuksia. Tämä ohjelmointirajapinnan käyttö edellyttää OAuth2.0-todennusta. Lisätietoja on artikkelissa OAuth 2.0 -valtuutuskoodin kulku.

Yleensä sinun on suoritettava seuraavat vaiheet, jotta voit käyttää näitä ohjelmointirajapintoja:

• Luo Microsoft Entra sovellus.
• Hanki käyttöoikeustietue tämän sovelluksen avulla.
• Käytä tunnusta Microsoft Defender XDR-ohjelmointirajapintaan.

Koska tämä sovellus on usean vuokraajan sovellus, tarvitset myös kunkin vuokraajan järjestelmänvalvojan suostumuksen sen käyttäjien puolesta.

Tässä artikkelissa kerrotaan, miten:

• Usean vuokraajan Microsoft Entra sovelluksen luominen
• Pyydä sovellukseltasi valtuutettu suostumus käyttää Microsoft Defender XDR, joita se tarvitsee.
• Hanki Microsoft Defender XDR käyttöoikeustietue
• Tunnuksen vahvistaminen

Microsoft Defender XDR paljastaa suuren osan tiedoistaan ja toiminnoistaan ohjelmallisten ohjelmointirajapintojen avulla. Näiden ohjelmointirajapintojen avulla voit automatisoida työnkulkuja ja innovoida Microsoft Defender XDR ominaisuuksien perusteella. Ohjelmointirajapinnan käyttö edellyttää OAuth2.0-todennusta. Lisätietoja on artikkelissa OAuth 2.0 -valtuutuskoodin kulku.

Yleensä sinun on suoritettava seuraavat vaiheet ohjelmointirajapintoja varten:

• Luo usean vuokraajan Microsoft Entra sovellus.
• Pyydä käyttäjäsi järjestelmänvalvojalta valtuutettu suostumus sille, että sovellus voi käyttää tarvitsemiaan Microsoft Defender XDR resursseja.
• Hanki käyttöoikeustietue tämän sovelluksen avulla.
• Käytä tunnusta Microsoft Defender XDR-ohjelmointirajapintaan.

Seuraavissa vaiheissa annetaan ohjeet usean vuokraajan Microsoft Entra sovelluksen luomiseen, käyttöoikeustietueen hankkimiseen Microsoft Defender XDR ja tunnuksen vahvistamiseen.

Usean vuokraajan sovelluksen luominen

1. Kirjaudu sisään Azureen.

2. Siirry kohtaan Microsoft Entra ID>Sovelluksen rekisteröinnit>Uusi rekisteröinti.

   

3. Rekisteröintilomakkeessa:

   • Valitse sovellukselle nimi.
   • Valitse Tuetut tilityypit -kohdasta Tilit missä tahansa organisaatiohakemistossa (mikä tahansa Microsoft Entra hakemisto) – Monitoiminen.
   • Täytä Uudelleenohjauksen URI - osa. Valitse kirjoita Verkko ja anna uudelleenohjauksen URI-tunnus muodossa https://portal.azure.com.

   Kun olet täyttänyt lomakkeen, valitse Rekisteröi.

   

4. Valitse sovellussivulla ohjelmointirajapinnan käyttöoikeudetLisää käyttöoikeuksien>ohjelmointirajapinnat>, joita organisaationi käyttää>, kirjoita Microsoft Threat Protection ja valitse Microsoft Threat Protection. Sovelluksesi voi nyt käyttää Microsoft Defender XDR.

   Vihje

   Microsoft Threat Protection on Microsoft Defender XDR entinen nimi, eikä sitä näytetä alkuperäisessä luettelossa. Sinun on alettava kirjoittaa sen nimeä tekstiruutuun, jotta näet sen näkyvän.

   

5. Valitse Sovelluksen käyttöoikeudet. Valitse skenaarioon liittyvät käyttöoikeudet (esimerkiksi Incident.Read.All) ja valitse sitten Lisää käyttöoikeuksia.

   

   Huomautus

   Sinun on valittava skenaarioon liittyvät käyttöoikeudet. Kaikkien tapausten lukeminen on vain esimerkki. Voit selvittää, minkä käyttöoikeuden tarvitset, katsomalla käyttöoikeusosiota ohjelmointirajapinnassa, johon haluat soittaa.

   Jos haluat esimerkiksi suorittaa kehittyneitä kyselyitä, valitse Suorita kehittyneet kyselyt -käyttöoikeus. jos haluat eristää laitteen, valitse Eristä kone -käyttöoikeus.

6. Valitse Myönnä järjestelmänvalvojan suostumus. Aina, kun lisäät käyttöoikeuden, sinun on valittava Myönnä järjestelmänvalvojan suostumus , jotta se tulee voimaan.

   

7. Lisää sovellukselle salaisuus valitsemalla Varmenteet & salaisuuksia, lisäämällä kuvauksen salauskoodiin ja valitsemalla sitten Lisää.

   Vihje

   Kun olet valinnut Lisää, valitse kopioi luotu salaisen koodin arvo. Et voi noutaa salaisen koodin arvoa poistuttuasi.

   

8. Tallenna sovellustunnuksesi ja vuokraajatunnuksesi jonnekin turvalliseen paikkaan. Ne on lueteltu sovellussivulla Yleiskatsaus-kohdassa .

   

9. Lisää sovellus käyttäjän vuokraajaan.

   Koska sovelluksesi on vuorovaikutuksessa Microsoft Defender XDR kanssa käyttäjiesi puolesta, se on hyväksyttävä jokaiselle vuokraajalle, jossa aiot käyttää sitä.

   Käyttäjän vuokraajan järjestelmänvalvojan on tarkasteltava suostumuslinkkiä ja hyväksyttävä sovelluksesi.

   Suostumuslinkki on muodossa:

   https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
   

   Numerot 00000000-0000-0000-0000-000000000000 tulee korvata sovellustunnuksellasi.

   Kun olet napsauttanut suostumuslinkkiä, kirjaudu sisään käyttäjän vuokraajan järjestelmänvalvojana ja myönnä suostumus sovellukselle.

   

   Sinun on myös pyydettävä käyttäjältäsi vuokraajatunnusta. Vuokraajatunnus on yksi tunnisteista, joita käytetään käyttöoikeustietueiden hankkimiseen.

• Valmis! Olet rekisteröinyt sovelluksen!
• Alla on esimerkkejä tunnuksen hankkimisesta ja vahvistamisesta.

Käyttöoikeustietueen hankkiminen

Lisätietoja Microsoft Entra tunnuksista on Microsoft Entra opetusohjelmassa.

Tärkeää

Vaikka tämän osion esimerkeissä kannustetaan liittämään salaisia arvoja testausta varten, salaisuuksia ei tule koskaan koodata kiinteästi sovelluksessa, joka on käynnissä tuotannossa. Kolmas osapuoli voi käyttää salaisuuttasi resurssien käyttämiseen. Voit auttaa pitämään sovelluksesi salaisuudet suojattuina käyttämällä Azure Key Vault. Käytännön esimerkki siitä, miten voit suojata sovellustasi, on artikkelissa Salaisten koodien hallinta palvelinsovelluksissa Azure Key Vault avulla.

Vihje

Seuraavissa esimerkeissä voit testata komentosarjan toimimista käyttäjän vuokraajatunnuksella.

Käyttöoikeustietueen hankkiminen PowerShellin avulla

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

Käyttöoikeustietueen hankkiminen C:n avulla#

Huomautus

Seuraava koodi testattiin nuget Microsoft.Identity.Client 3.19.8:lla.

Tärkeää

Microsoft.IdentityModel.Clients.ActiveDirectory NuGet -paketti ja Azure AD Authentication Library (ADAL) on vanhentunut. Uusia ominaisuuksia ei ole lisätty 30.6.2020 jälkeen. Suosittelemme sinua päivittämään, katso lisätietoja siirto-oppaasta .

1. Luo uusi konsolisovellus.

2. Asenna NuGet Microsoft.Identity.Client.

3. Lisää seuraava rivi:

   using Microsoft.Identity.Client;
   

4. Kopioi ja liitä seuraava koodi sovellukseesi (muista päivittää kolme muuttujaa: tenantId, clientId, appSecret):

   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // 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 = https://api.securitycenter.microsoft.com;
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

Käyttöoikeustietueen hankkiminen Pythonin avulla

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Hanki käyttöoikeustietue käyttämällä curlia

Huomautus

Curl on esiasennettu Windows 10 versioon 1803 ja uudempiin versioihin. Lataa ja asenna työkalu muille Windows-versioille suoraan viralliselta curl-sivustolta.

1. Avaa komentokehote ja määritä CLIENT_ID Azure-sovellustunnuksellesi.
2. Määritä CLIENT_SECRET Azure-sovelluksen salauskoodiin.
3. Määritä TENANT_ID sen käyttäjän Azure-vuokraajatunnukseen, joka haluaa käyttää Microsoft Defender XDR sovelluksessasi.
4. Suorita seuraava komento:

curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Onnistunut vastaus näyttää tältä:

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

Tunnuksen vahvistaminen

1. Kopioi ja liitä tunnus JSON-verkkotunnuksen vahvistajasivustoon JWT , jotta sen koodaus puretaan.
2. Varmista, että koodatun tunnuksen roolit sisältävät halutut käyttöoikeudet.

Seuraavassa kuvassa näet sovelluksesta hankitun koodatun tunnuksen, jolla on Incidents.Read.All, Incidents.ReadWrite.Allja AdvancedHunting.Read.All -käyttöoikeudet:

Microsoft Defender XDR-ohjelmointirajapinnan käyttäminen tunnuksen avulla

1. Valitse ohjelmointirajapinta, jota haluat käyttää (tapaukset tai kehittynyt metsästys). Lisätietoja on kohdassa Tuetut Microsoft Defender XDR-ohjelmointirajapinnat.
2. Määritä lähetettävässä http-pyynnössä valtuutusotsikoksi "Bearer" <token>, haltija on valtuutusmalli ja tunnus on vahvistettu tunnus.
3. Tunnus vanhenee tunnin kuluessa. Voit lähettää tänä aikana useamman kuin yhden pyynnön samalla tunnuuksella.

Seuraavassa esimerkissä näytetään, miten voit lähettää pyynnön, jotta saat luettelon tapauksista C#:n avulla.

   var httpClient = new HttpClient();
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

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

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

Aiheeseen liittyviä artikkeleita

• Microsoft Defender XDR ohjelmointirajapintoja yleiskatsaus
• Microsoft Defender XDR-ohjelmointirajapinnoille pääsy
• Hello maailman sovelluksen luominen
• Sovelluksen luominen Microsoft Defender XDR käyttämiseksi ilman käyttäjää
• Sovelluksen luominen Microsoft Defender XDR ohjelmointirajapintojen käyttämiseksi käyttäjän puolesta
• Lisätietoja ohjelmointirajapinnan rajoituksista ja käyttöoikeuksista
• Virhekoodien ymmärtäminen
• Salaisten koodien hallinta palvelinsovelluksissa Azure-Key Vault
• OAuth 2.0 -valtuutus käyttäjän kirjautumiselle ja ohjelmointirajapinnan käyttöoikeudelle

Vihje

Haluatko tietää lisää? Ota yhteyttä Microsoft Security -yhteisöön Tech Community -yhteisössä: Microsoft Defender XDR Tech Community.