Megosztás a következőn keresztül:

Microsoft Defender XDR API-khoz partneri hozzáféréssel rendelkező alkalmazás Létrehozás

  • Cikk

Érintett szolgáltatás:

  • Microsoft Defender XDR

Fontos

Bizonyos információk az előzetesen forgalomba hozott termékre vonatkoznak, amely a kereskedelmi forgalomba kerülés előtt lényegesen módosulhat. A Microsoft nem vállal semmilyen, kifejezett vagy vélelmezett jótállást az itt megadott információkra vonatkozóan.

Ez az oldal bemutatja, hogyan hozhat létre olyan Microsoft Entra alkalmazást, amely programozott hozzáféréssel rendelkezik a Microsoft Defender XDR több bérlő felhasználói nevében. A több-bérlős alkalmazások nagy felhasználói csoportok kiszolgálásához hasznosak.

Ha programozott hozzáférésre van szüksége ahhoz, hogy egyetlen felhasználó nevében Microsoft Defender XDR, tekintse meg az alkalmazás Létrehozás Microsoft Defender XDR API-k felhasználó nevében való eléréséhez című témakört. Ha explicit módon definiált felhasználó nélküli hozzáférésre van szüksége (például háttéralkalmazás vagy démon írásakor), tekintse meg Létrehozás egy alkalmazást a felhasználó nélküli Microsoft Defender XDR eléréséhez című témakörben. Ha nem tudja biztosan, hogy milyen típusú hozzáférésre van szüksége, olvassa el az Első lépések című témakört.

Microsoft Defender XDR az adatok és műveletek nagy részét programozott API-k segítségével teszi elérhetővé. Ezek az API-k segítenek automatizálni a munkafolyamatokat, és kihasználni Microsoft Defender XDR képességeit. Ehhez az API-hozzáféréshez OAuth2.0-hitelesítés szükséges. További információ: OAuth 2.0 engedélyezési kódfolyamat.

Ezeknek az API-knak a használatához általában a következő lépéseket kell elvégeznie:

  • Microsoft Entra alkalmazás Létrehozás.
  • Hozzáférési jogkivonat lekérése ezzel az alkalmazással.
  • A jogkivonattal érheti el Microsoft Defender XDR API-t.

Mivel ez az alkalmazás több-bérlős, rendszergazdai hozzájárulásra is szüksége lesz az egyes bérlőktől a felhasználók nevében.

Ez a cikk a következő lépéseket ismerteti:

  • Több-bérlős Microsoft Entra alkalmazás Létrehozás
  • Kérje meg a felhasználói rendszergazda engedélyét az alkalmazáshoz a szükséges erőforrások Microsoft Defender XDR eléréséhez.
  • Hozzáférési jogkivonat lekérése a Microsoft Defender XDR
  • A jogkivonat ellenőrzése

Microsoft Defender XDR az adatok és műveletek nagy részét programozott API-k segítségével teszi elérhetővé. Ezek az API-k segítenek automatizálni a munkafolyamatokat és az innovációt Microsoft Defender XDR képességek alapján. Az API-hozzáféréshez OAuth2.0-hitelesítés szükséges. További információ: OAuth 2.0 engedélyezési kódfolyamat.

Az API-k használatához általában a következő lépéseket kell elvégeznie:

  • több-bérlős Microsoft Entra alkalmazás Létrehozás.
  • Kérje meg a felhasználói rendszergazda engedélyét (hozzájárulását) az alkalmazáshoz, hogy hozzáférjen Microsoft Defender XDR szükséges erőforrásokhoz.
  • Hozzáférési jogkivonat lekérése ezzel az alkalmazással.
  • A jogkivonattal érheti el Microsoft Defender XDR API-t.

Az alábbi lépések bemutatja, hogyan hozhat létre több-bérlős Microsoft Entra alkalmazást, hogyan kérhet le hozzáférési jogkivonatot a jogkivonat Microsoft Defender XDR és érvényesítéséhez.

A több-bérlős alkalmazás Létrehozás

  1. Jelentkezzen be az Azure-baglobális rendszergazdai szerepkörrel rendelkező felhasználóként.

  2. Lépjen a Microsoft Entra ID>Alkalmazásregisztrációk>Új regisztráció elemre.

    Egy alkalmazás regisztrációs szakasza a Microsoft Defender portálon

  3. A regisztrációs űrlapon:

    • Válasszon nevet az alkalmazásnak.
    • A Támogatott fióktípusok területen válassza a Fiókok bármely szervezeti címtárban (Bármely Microsoft Entra címtárban) – Több-bérlő lehetőséget.
    • Töltse ki az Átirányítási URI szakaszt. Válassza a Web típust, és adja meg az átirányítási URI-t a következőnek: https://portal.azure.com.

    Miután kitöltötte az űrlapot, válassza a Regisztráció lehetőséget.

    Egy alkalmazás regisztrációs szakaszai a Microsoft Defender portálon

  4. Az alkalmazás oldalán válassza az API-engedélyek>Engedély hozzáadása>API-kat>, írja be a Microsoft Threat Protection kifejezést, majd válassza a Microsoft Threat Protection lehetőséget. Az alkalmazás most már hozzáférhet Microsoft Defender XDR.

    Tipp

    A Microsoft Threat Protection a Microsoft Defender XDR korábbi neve, és nem jelenik meg az eredeti listában. A megjelenítendő szövegmezőbe be kell írnia a nevét.

    Az API-k használata szakasz a Microsoft Defender portálon

  5. Válassza az Alkalmazásengedélyek lehetőséget. Válassza ki a forgatókönyv megfelelő engedélyeit (például Incident.Read.All), majd válassza az Engedélyek hozzáadása lehetőséget.

    Egy alkalmazás engedélypanelje a Microsoft Defender portálon

    Megjegyzés:

    Ki kell választania a forgatókönyvéhez tartozó megfelelő engedélyeket. Az összes incidens elolvasása csak egy példa. Annak megállapításához, hogy melyik engedélyre van szüksége, tekintse meg a meghívni kívánt API Engedélyek szakaszát.

    Speciális lekérdezések futtatásához például válassza a "Speciális lekérdezések futtatása" engedélyt; az eszköz elkülönítéséhez válassza a "Gép elkülönítése" engedélyt.

  6. Válassza a Rendszergazdai hozzájárulás megadása lehetőséget. Minden alkalommal, amikor hozzáad egy engedélyt, a rendszergazdai hozzájárulás megadása lehetőséget kell választania ahhoz, hogy érvénybe lépjen.

    A rendszergazdai hozzájárulás megadására szolgáló szakasz a Microsoft Defender portálon

  7. Ha titkos kódot szeretne hozzáadni az alkalmazáshoz, válassza a Tanúsítványok & titkos kód lehetőséget, adjon hozzá egy leírást a titkos kódhoz, majd válassza a Hozzáadás lehetőséget.

    Tipp

    A Hozzáadás lehetőség kiválasztása után válassza a létrehozott titkos kód értékének másolása lehetőséget. A kilépés után nem fogja tudni lekérni a titkos kulcsot.

    A Titkos kulcs hozzáadása szakasz a Microsoft Defender portálon

  8. Jegyezze fel az alkalmazásazonosítót és a bérlőazonosítót biztonságos helyen. Ezek az alkalmazásoldal Áttekintés területén jelennek meg.

    Az Áttekintés panel a Microsoft Defender portálon

  9. Adja hozzá az alkalmazást a felhasználó bérlőjéhez.

    Mivel az alkalmazás a felhasználók nevében kommunikál a Microsoft Defender XDR, minden olyan bérlő számára jóvá kell hagyni, amelyen használni kívánja.

    A felhasználó bérlőjének globális rendszergazdájának meg kell tekintenie a hozzájárulási hivatkozást, és jóvá kell hagynia az alkalmazást.

    A hozzájárulási hivatkozás formátuma:

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

    A számjegyeket 00000000-0000-0000-0000-000000000000 az alkalmazásazonosítóra kell cserélni.

    Miután a hozzájárulási hivatkozásra kattintott, jelentkezzen be a felhasználó bérlőjének globális rendszergazdájával, és hagyja jóvá az alkalmazást.

    A hozzájárulási alkalmazás lapja a Microsoft Defender portálon

    Emellett meg kell kérnie a felhasználótól a bérlőazonosítóját. A bérlőazonosító a hozzáférési jogkivonatok beszerzéséhez használt azonosítók egyike.

  • Kész! Sikeresen regisztrált egy alkalmazást!
  • A jogkivonatok beszerzéséről és érvényesítéséről alább talál példákat.

Hozzáférési jogkivonat lekérése

A Microsoft Entra tokenekről az Microsoft Entra oktatóanyagban talál további információt.

Fontos

Bár az ebben a szakaszban szereplő példák arra ösztönzik, hogy tesztelési célokra illessze be a titkos kulcsokat, soha ne kódoljon titkos kódokat éles környezetben futó alkalmazásokba. Egy harmadik fél felhasználhatja az Ön titkos kódját az erőforrások eléréséhez. Az Azure Key Vault segítségével biztonságban tarthatja az alkalmazás titkos kulcsát. Az alkalmazás védelmének gyakorlati példájáért lásd: Titkos kódok kezelése a kiszolgálóalkalmazásokban az Azure Key Vault használatával.

Tipp

Az alábbi példákban egy felhasználó bérlőazonosítójával tesztelje, hogy a szkript működik-e.

Hozzáférési jogkivonat lekérése a PowerShell használatával

# 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

Hozzáférési jogkivonat lekérése a C használatával#

Megjegyzés:

A következő kódot a Nuget Microsoft.Identity.Client 3.19.8-val teszteltük.

Fontos

A Microsoft.IdentityModel.Clients.ActiveDirectory NuGet-csomag és Azure AD Authentication Library (ADAL) elavult. 2020. június 30. óta nem adhatók hozzá új funkciók. Javasoljuk, hogy frissítsen. További részletekért tekintse meg a migrálási útmutatót .

  1. Létrehozás egy új konzolalkalmazást.

  2. Telepítse a NuGet Microsoft.Identity.Client eszközt.

  3. Adja hozzá a következő sort:

    using Microsoft.Identity.Client;

  4. Másolja és illessze be a következő kódot az alkalmazásba (ne felejtse el frissíteni a három változót: 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;

Hozzáférési jogkivonat lekérése a Python használatával

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"]

Hozzáférési jogkivonat lekérése a curl használatával

Megjegyzés:

A Curl előre telepítve van a Windows 10 1803-at és újabb verzióit. A Windows egyéb verziói esetén töltse le és telepítse az eszközt közvetlenül a curl hivatalos webhelyéről.

  1. Nyisson meg egy parancssort, és állítsa CLIENT_ID az Azure-alkalmazásazonosítóra.
  2. Állítsa CLIENT_SECRET az Azure-alkalmazás titkos kódjára.
  3. Állítsa a TENANT_ID annak a felhasználónak az Azure-bérlőazonosítójára, aki az alkalmazást szeretné használni a Microsoft Defender XDR eléréséhez.
  4. Futtassa az alábbi parancsot:
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

A sikeres válasz így fog kinézni:

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

A jogkivonat ellenőrzése

  1. Másolja és illessze be a jogkivonatot a JSON webes jogkivonat-érvényesítő webhelyére (JWT) a dekódolásához.
  2. Győződjön meg arról, hogy a dekódolt jogkivonaton belüli szerepkörjogcím tartalmazza a kívánt engedélyeket.

Az alábbi képen egy alkalmazásból beszerzett dekódolt jogkivonatot láthat, amely Incidents.Read.Alla , Incidents.ReadWrite.Alla és AdvancedHunting.Read.All az engedélyekkel rendelkezik:

A Dekódolt jogkivonat panel a Microsoft Defender portálon

A jogkivonat használata a Microsoft Defender XDR API eléréséhez

  1. Válassza ki a használni kívánt API-t (incidensek vagy speciális veszélyforrás-keresés). További információ: Támogatott Microsoft Defender XDR API-k.
  2. Az elküldeni kívánt HTTP-kérelemben állítsa az engedélyezési fejlécet a következőre "Bearer" <token>: , Tulajdonos az engedélyezési séma, a jogkivonat pedig az érvényesített jogkivonat.
  3. A jogkivonat egy órán belül lejár. Ez idő alatt több kérést is küldhet ugyanazzal a jogkivonattal.

Az alábbi példa bemutatja, hogyan küldhet kérést az incidensek listájának lekéréséhez a C# használatával.

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

Tipp

Szeretne többet megtudni? Lépjen kapcsolatba a Microsoft biztonsági közösségével a technikai közösségünkben: Microsoft Defender XDR Tech Community.