Partnerhozzáférés a Végponthoz készült Microsoft Defender API-kkal

Érintett szolgáltatás:

• Végponthoz készült Microsoft Defender 1. csomag
• Végponthoz készült Microsoft Defender 2. csomag
• Microsoft Defender Vállalati verzió

Fontos

A Speciális veszélyforrás-keresési képességek nem szerepelnek a Defender Vállalati verzióban.

Szeretné megismerni a Végponthoz készült Microsoft Defendert? Regisztráció az ingyenes próbaverzióra

Megjegyzés:

Ha Ön az USA kormányzati szerveinek ügyfele, használja az USA kormányzati ügyfeleinek készült Végponthoz készült Microsoft Defenderben felsorolt URI-kat.

Tipp

A jobb teljesítmény érdekében a földrajzi helyhez közelebbi kiszolgálót használhat:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com

Ez az oldal bemutatja, hogyan hozhat létre Microsoft Entra-alkalmazást, hogy programozott hozzáférést kapjon a Végponthoz készült Microsoft Defenderhez az ügyfelek nevében.

A Végponthoz készült 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 az innovációt a Végponthoz készült Microsoft Defender képességei 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:

1. Több-bérlős Microsoft Entra-alkalmazás létrehozása.

2. Kérje meg az ügyfél rendszergazdájának engedélyét (hozzájárulását) az alkalmazáshoz, hogy hozzáférjen a Defender for Endpoint-erőforrásokhoz, amelyekre szüksége van.

3. Hozzáférési jogkivonat lekérése ezzel az alkalmazással.

4. A jogkivonat használatával érheti el a Végponthoz készült Microsoft Defender API-t.

Az alábbi lépésekből megtudhatja, hogyan hozhat létre Microsoft Entra-alkalmazást, hogyan kérhet le hozzáférési jogkivonatot a Végponthoz készült Microsoft Defenderhez, és hogyan ellenőrizheti a jogkivonatot.

Fontos

A Microsoft azt javasolja, hogy a legkevesebb engedéllyel rendelkező szerepköröket használja. Ez segít a szervezet biztonságának javításában. A globális rendszergazda egy kiemelt jogosultságokkal rendelkező szerepkör, amelyet vészhelyzeti helyzetekre kell korlátozni, ha nem használhat meglévő szerepkört.

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

1. Jelentkezzen be az Azure-bérlőbeglobális rendszergazdai szerepkörrel rendelkező felhasználóval.

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

   

3. A regisztrációs űrlapon:

   • Válasszon nevet az alkalmazásnak.

   • Támogatott fióktípusok – bármely szervezeti címtárban található fiókok.

   • Átirányítási URI – típus: Web, URI: https://portal.azure.com

     

4. Engedélyezze az alkalmazás számára a Végponthoz készült Microsoft Defender elérését, és rendelje hozzá az integráció befejezéséhez szükséges minimális engedélyekkel.

   • Az alkalmazás oldalán válassza az API-engedélyek>Engedély hozzáadása>API-k a szervezet általa WindowsDefenderATP típust használ>, majd válassza a WindowsDefenderATP lehetőséget.

   • WindowsDefenderATP nem jelenik meg az eredeti listában. Kezdje el beírni a nevét a szövegmezőbe, hogy megjelenjen.

     

API-engedélyek kérése

Annak megállapításához, hogy melyik engedélyre van szüksége, tekintse át a meghívni kívánt API Engedélyek szakaszát. Például:

• Speciális lekérdezések futtatásához 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.

Az alábbi példában az Összes riasztás olvasása engedélyt használjuk:

1. Válassza az Alkalmazásengedélyek>Alert.Read.All> lehetőséget az Engedélyek hozzáadása területen.

   

2. Válassza a Hozzájárulás megadása lehetőséget

   • Minden alkalommal, amikor engedélyt ad hozzá, a Hozzájárulás megadása lehetőséget kell választania az új engedély érvénybe léptetéséhez.

   

3. Adjon hozzá egy titkos kódot az alkalmazáshoz.

   • Válassza a Tanúsítványok & titkos kód lehetőséget, adja meg a titkos kód leírását, majd válassza a Hozzáadás lehetőséget.

   A Hozzáadás lehetőség kiválasztása után mindenképpen másolja ki a létrehozott titkos kulcsot. Miután elment, nem fogja tudni lekérni!

   

4. Jegyezze fel az alkalmazásazonosítót:

   • Az alkalmazás oldalán lépjen az Áttekintés lapra, és másolja ki a következő információkat:

     

5. Adja hozzá az alkalmazást az ügyfél bérlőjéhez.

   Minden olyan ügyfélbérlőben jóvá kell hagynia az alkalmazást, ahol használni szeretné. Erre a jóváhagyásra azért van szükség, mert az alkalmazás az ügyfél nevében kommunikál a Végponthoz készült Microsoft Defender alkalmazással.

   Az ügyfél bérlőjének globális rendszergazdájával rendelkező felhasználónak ki kell választania 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
   

   Hol 00000000-0000-0000-0000-000000000000 kell lecserélni az alkalmazásazonosítót.

   A hozzájárulási hivatkozás kiválasztása után jelentkezzen be az ügyfél bérlőjének globális rendszergazdájaként, és hagyja jóvá az alkalmazást.

   

   Emellett meg kell kérnie az ügyfelet a bérlőazonosítójáért, és mentenie kell azt későbbi használatra a jogkivonat beszerzésekor.

6. Kész! Sikeresen regisztrált egy alkalmazást! A jogkivonatok beszerzéséhez és érvényesítéséhez tekintse meg az alábbi példákat.

Példa hozzáférési jogkivonat lekérése

Ha az ügyfél nevében szeretné lekérni a hozzáférési jogkivonatot, használja az ügyfél bérlőazonosítóját a következő jogkivonat-beszerzések során.

A Microsoft Entra-tokenről további információt a Microsoft Entra oktatóanyagában talál.

A PowerShell használata

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    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

A C használata#

Fontos

A Microsoft.IdentityModel.Clients.ActiveDirectory NuGet-csomag és az Azure AD Authentication Library (ADAL) elavult. 2020. június 30. óta nem adhatók hozzá új funkciók. A frissítéshez 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őt kód használatával:

    using Microsoft.Identity.Client;
   

   Ezt a kódot a NuGettel Microsoft.Identity.Clientteszteltük.

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

A Python használata

Lásd: Jogkivonat lekérése a Python használatával.

A Curl használata

Megjegyzés:

Az alábbi eljárás feltételezi, hogy a Windows Curl már telepítve van a számítógépen

1. Nyisson meg egy parancsablakot.

2. Állítsa be CLIENT_ID az Azure-alkalmazásazonosítót.

3. Állítsa be CLIENT_SECRET az Azure-alkalmazás titkos kódját.

4. Állítsa be TENANT_ID annak az ügyfélnek az Azure-bérlőazonosítóját, aki az alkalmazást szeretné használni a Végponthoz készült Microsoft Defender alkalmazás eléréséhez.

5. 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 következő kódrészlethez hasonló választ kap:

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

A jogkivonat ellenőrzése

Ellenőrizze, hogy helyes jogkivonatot kapott-e.

1. Másolja/illessze be a JWT-be az előző lépésben lekért jogkivonatot a dekódolásához.

2. Győződjön meg arról, hogy a megfelelő engedélyekkel rendelkező szerepkör-jogcímet kap.

   Az alábbi képernyőképen egy, a Végponthoz készült Microsoft Defenderhez több engedéllyel rendelkező alkalmazásból beszerzett dekódolt jogkivonat látható:

   

   A "tid" jogcím az a bérlőazonosító, amelyhez a jogkivonat tartozik.

A jogkivonat használata a Végponthoz készült Microsoft Defender API eléréséhez

1. Válassza ki a használni kívánt API-t. További információ: A Végponthoz készült Microsoft Defender API-k támogatottak.

2. Állítsa be az Engedélyezés fejlécet a http-kérésben, amelyre elküldi Bearer {token} (a Tulajdonos az engedélyezési séma). A jogkivonat lejárati ideje egy óra (több kérést is elküldhet ugyanazzal a jogkivonattal).

   Íme egy példa arra, hogyan küldhet egy kérést a riasztások listájának lekéréséhez a C# használatával:

   var httpClient = new HttpClient();
   
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
   
   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
   
   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
   
    // Do something useful with the response
   

Lásd még

• Támogatott Végponthoz készült Microsoft Defender API-k
• A Végponthoz készült Microsoft Defender elérése egy felhasználó nevében

Tipp

Szeretne többet megtudni? Vegye fel a kapcsolatot a Microsoft Security közösségével a technikai közösségünkben: Microsoft Defender for Endpoint Tech Community.