Microsoft Defender for Endpoint API を使用したパートナーアクセス

[アーティクル]
06/29/2024

適用対象:

重要

Defender for Business には高度なハンティング機能は含まれていません。

Microsoft Defender ATP を試してみたいですか? 無料試用版にサインアップしてください。

注:

米国政府機関のお客様は、 Microsoft Defender for Endpoint for US Government のお客様に記載されている URI を使用してください。

ヒント

パフォーマンスを向上させるために、地理的な場所に近いサーバーを使用できます。

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

このページでは、Microsoft Entra アプリケーションを作成して、顧客に代わって Microsoft Defender for Endpoint にプログラムでアクセスする方法について説明します。

Microsoft Defender for Endpoint は、一連のプログラム API を通じて、そのデータとアクションの多くを公開します。これらの API は、Microsoft Defender for Endpoint 機能に基づいて作業フローを自動化し、イノベーションを行うのに役立ちます。 API アクセスには OAuth2.0 認証が必要です。詳細については、「 OAuth 2.0 承認コードフロー」を参照してください。

一般に、API を使用するには、次の手順を実行する必要があります。

マルチテナント Microsoft Entra アプリケーションを作成します。
顧客管理者が、必要な Defender for Endpoint リソースにアクセスするためのアプリケーションの承認 (同意) を取得します。
このアプリケーションを使用してアクセストークンを取得します。
トークンを使用して Microsoft Defender for Endpoint API にアクセスします。

次の手順では、Microsoft Entra アプリケーションを作成し、Microsoft Defender for Endpoint へのアクセストークンを取得し、トークンを検証する方法について説明します。

重要

Microsoft では、アクセス許可が可能な限りで少ないロールを使用することをお勧めします。これにより、組織のセキュリティが向上します。グローバル管理者は高い特権を持つロールであり、既存のロールを使用できない場合の緊急時に限定する必要があります。

マルチテナントアプリを作成する

グローバル管理者ロールを持つユーザーを使用して Azure テナントにサインインします。
[Microsoft Entra ID>App registrations>新しい登録] に移動します。
登録フォームで、次の手順を実行します。
- アプリケーションの名前を選択します。
- サポートされているアカウントの種類 - 任意の組織のディレクトリ内のアカウント。
- リダイレクト URI - 型: Web、URI: https://portal.azure.com
アプリケーションが Microsoft Defender for Endpoint にアクセスし、統合を完了するために必要な最小限のアクセス許可セットで割り当てることを許可します。
- アプリケーションページで、[API のアクセス許可]、[アクセス許可の追加>>AP]を選択します。組織が使用する API は>「WindowsDefenderATP」と入力し、WindowsDefenderATP を選択します。
- WindowsDefenderATP は元のリストに表示されません。テキストボックスに名前を書き込み、表示されるようにします。

API のアクセス許可を要求する

必要なアクセス許可を確認するには、呼び出す API の [アクセス許可] セクションを確認します。例:

高度なクエリを実行するには、[高度なクエリの実行] アクセス許可を選択します。
デバイスを分離するには、[マシンの分離] アクセス許可を選択します。

次の例では、 すべてのアラートの読み取り アクセス許可を使用します。

[アプリケーションのアクセス許可] を選択>Alert.Read.All>[アクセス許可の追加] を選択します
[ 同意の付与] を選択します
- アクセス許可を追加するたびに、[新しいアクセス許可を有効にするために 同意を付与 する] を選択する必要があります。
アプリケーションにシークレットを追加します。
- [ 証明書 & シークレット] を選択し、シークレットに説明を追加し、[ 追加] を選択します。
[追加] を選択したら、生成されたシークレット値を必ずコピーしてください。退出後は取得できません。
アプリケーション ID を書き留めます。
- アプリケーションページで、[ 概要 ] に移動し、次の情報をコピーします。
アプリケーションを顧客のテナントに追加します。

アプリケーションを使用する各顧客テナントでアプリケーションを承認する必要があります。アプリケーションが顧客の代わりに Microsoft Defender for Endpoint アプリケーションと対話するため、この承認が必要です。

顧客のテナントから グローバル管理者 を持つユーザーは、同意リンクを選択し、アプリケーションを承認する必要があります。

同意リンクは次の形式です。
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
ここで、 00000000-0000-0000-0000-000000000000 をアプリケーション ID に置き換える必要があります。

同意リンクを選択したら、顧客のテナントのグローバル管理者としてサインインし、アプリケーションに同意します。

$[Accept]$同意$ ボタン$

さらに、顧客にテナント ID を要求し、トークンを取得するときに将来使用できるように保存する必要があります。
完了! アプリケーションを正常に登録しました。トークンの取得と検証については、次の例を参照してください。

アクセストークンの例を取得する

顧客に代わってアクセストークンを取得するには、次のトークン取得で顧客のテナント ID を使用します。

Microsoft Entra トークンの詳細については、「 Microsoft Entra チュートリアル」を参照してください。

PowerShell の使用

# 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

C の使用#

重要

Microsoft.IdentityModel.Clients.ActiveDirectory NuGet パッケージと Azure AD Authentication Library (ADAL) は非推奨になりました。 2020 年 6 月 30 日以降、新機能は追加されていません。アップグレードするには、移行ガイドを参照してください。

新しいコンソールアプリケーションを作成します。
NuGet Microsoft.Identity.Client をインストールします。
コードを使用して次を追加します。
```
 using Microsoft.Identity.Client;
```
このコードは NuGet Microsoft.Identity.Clientでテストされました。

アプリケーションに次のコードをコピー/貼り付けます ( tenantId、 appId、 appSecretの 3 つの変数を更新することを忘れないでください)。

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;

Python の使用

「Python を使用してトークンを取得する」を参照してください。

Curl の使用

注:

次の手順では、Curl for Windows がコンピューターに既にインストールされていると想定されています

コマンドウィンドウを開きます。
CLIENT_IDを Azure アプリケーション ID に設定します。
CLIENT_SECRETを Azure アプリケーションシークレットに設定します。
TENANT_IDを、アプリケーションを使用して Microsoft Defender for Endpoint アプリケーションにアクセスする顧客の Azure テナント ID に設定します。

次のコマンドを実行します。

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

次のコードスニペットのような回答が得られます。

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

トークンを検証する

正しいトークンを受け取ったかどうかを確認します。

前の手順で取得したトークンを JWT にコピー/貼り付けてデコードします。
適切なアクセス許可を持つロール要求を取得することを確認します。

次のスクリーンショットでは、Microsoft Defender for Endpoint に対する複数のアクセス許可を持つアプリケーションから取得したデコードされたトークンを確認できます。

"tid" 要求は、トークンが属するテナント ID です。

トークンを使用して Microsoft Defender for Endpoint API にアクセスする

使用する API を選択します。詳細については、「サポートされている Microsoft Defender for Endpoint API」を参照してください。
Bearer {token}に送信する Http 要求で Authorization ヘッダーを設定します (ベアラーは承認スキームです)。トークンの有効期限は 1 時間です (同じトークンで複数の要求を送信できます)。

C# を使用してアラートの一覧を取得する要求を送信する例を次に示します。
```
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
```

次の方法で共有

Microsoft Defender for Endpoint API を使用したパートナーアクセス

マルチテナントアプリを作成する

API のアクセス許可を要求する

アクセストークンの例を取得する

PowerShell の使用

C の使用#

Python の使用

Curl の使用

トークンを検証する

トークンを使用して Microsoft Defender for Endpoint API にアクセスする

関連項目

フィードバック

その他のリソース

次の方法で共有

Microsoft Defender for Endpoint API を使用したパートナー アクセス

マルチテナント アプリを作成する

API のアクセス許可を要求する

アクセス トークンの例を取得する

PowerShell の使用

C の使用#

Python の使用

Curl の使用

トークンを検証する

トークンを使用して Microsoft Defender for Endpoint API にアクセスする

関連項目

フィードバック

その他のリソース

Microsoft Defender for Endpoint API を使用したパートナーアクセス

マルチテナントアプリを作成する

アクセストークンの例を取得する