Alkalmazás létrehozása Microsoft Defender XDR API-khoz való partneri hozzáféréssel

  • A következőre érvényes:: 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.

Hozzon létre egy Microsoft Entra alkalmazást, amely programozott hozzáféréssel rendelkezik a Microsoft Defender 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 a Microsoft Defender egyetlen felhasználó nevében, olvassa el az alkalmazás létrehozása Microsoft Defender 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ása esetén), olvassa el az Alkalmazás létrehozása a felhasználó nélküli Microsoft Defender eléréséhez című témakört. 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 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 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:

  • Hozzon létre egy Microsoft Entra alkalmazást.
  • Hozzáférési jogkivonat lekérése ezzel az alkalmazással.
  • A jogkivonat használatával érheti el Microsoft Defender 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ása
  • Kérje meg a rendszergazdai hozzájárulást ahhoz, hogy az alkalmazás hozzáférjen a szükséges Microsoft Defender erőforrásokhoz.
  • Hozzáférési jogkivonat lekérése a Microsoft Defender
  • A jogkivonat ellenőrzése

Microsoft Defender 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 a munkafolyamatok automatizálásában és az Microsoft Defender képességeken alapuló innovációban. 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:

  • Hozzon létre egy több-bérlős Microsoft Entra alkalmazást.
  • Kérje meg a rendszergazdai hozzájárulást ahhoz, hogy az alkalmazás hozzáférjen a szükséges Microsoft Defender erőforrásokhoz.
  • Hozzáférési jogkivonat lekérése ezzel az alkalmazással.
  • A jogkivonat használatával érheti el Microsoft Defender API-t.

Az alábbi lépések végigvezetik egy több-bérlős Microsoft Entra alkalmazás létrehozásán, a hozzáférési jogkivonat Microsoft Defender való beszerzésén és a jogkivonat érvényesítésén.

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

  1. Jelentkezzen be a Azure.

  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, minden olyan bérlő számára jóvá kell hagyni, amelyen használni kívánja.

    A felhasználó bérlőjének 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 rendszergazdájaként, és adja meg a hozzájárulást az alkalmazáshoz.

    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 alkalmazás titkos kulcsainak védelmét Azure Key Vault használatával teheti biztonságossá. Az alkalmazás védelmének gyakorlati példájáért lásd: Titkos kódok kezelése a kiszolgálóalkalmazásokban Azure Key Vault.

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. Hozzon létre 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 a Azure alkalmazásazonosítóra.
  2. Állítsa CLIENT_SECRET a Azure alkalmazáskulcsra.
  3. Állítsa a TENANT_ID annak a felhasználónak a Azure bérlőazonosítójára, aki az alkalmazást szeretné használni a Microsoft Defender 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 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.

  • Last updated on