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

適用対象:

• Microsoft Defender for Endpoint Plan 1
• Microsoft Defender for Endpoint Plan 2
• Microsoft Defender for Business

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

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

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

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

1. マルチテナント Microsoft Entra アプリケーションを作成します。

2. 顧客管理者が、必要な Defender for Endpoint リソースにアクセスするためのアプリケーションの承認 (同意) を取得します。

3. このアプリケーションを使用してアクセス トークンを取得します。

4. トークンを使用して Microsoft Defender for Endpoint API にアクセスします。

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

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

1. グローバル管理者ロールを持つユーザーを使用して Azure テナントにサインインします。

2. [Microsoft Entra ID>App registrations>新しい登録] に移動します。

   

3. 登録フォームで、次の手順を実行します。

   • アプリケーションの名前を選択します。

   • サポートされているアカウントの種類 - 任意の組織のディレクトリ内のアカウント。

   • リダイレクト URI - 型: Web、URI: https://portal.azure.com

     

4. アプリケーションが Microsoft Defender for Endpoint にアクセスし、統合を完了するために必要な最小限のアクセス許可セットで割り当てることを許可します。

   • アプリケーション ページで、[API のアクセス許可]、[アクセス許可の追加>>AP]を選択します。組織が使用する API は>「WindowsDefenderATP」と入力し、WindowsDefenderATP を選択します。

   • WindowsDefenderATP は元のリストに表示されません。 テキスト ボックスに名前を書き込み、表示されるようにします。

     

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

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

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

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

1. [アプリケーションのアクセス許可] を選択>Alert.Read.All>[アクセス許可の追加] を選択します

   

2. [ 同意の付与] を選択します

   • アクセス許可を追加するたびに、[新しいアクセス許可を有効にするために 同意を付与 する] を選択する必要があります。

   

3. アプリケーションにシークレットを追加します。

   • [ 証明書 & シークレット] を選択し、シークレットに説明を追加し、[ 追加] を選択します。

   [追加] を選択したら、生成されたシークレット値を必ずコピーしてください。 退出後は取得できません。

   

4. アプリケーション ID を書き留めます。

   • アプリケーション ページで、[ 概要 ] に移動し、次の情報をコピーします。

     

5. アプリケーションを顧客のテナントに追加します。

   アプリケーションを使用する各顧客テナントでアプリケーションを承認する必要があります。 アプリケーションが顧客の代わりに 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 に置き換える必要があります。

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

   

   さらに、顧客にテナント ID を要求し、トークンを取得するときに将来使用できるように保存する必要があります。

6. 完了! アプリケーションを正常に登録しました。 トークンの取得と検証については、次の例を参照してください。

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

顧客に代わってアクセス トークンを取得するには、次のトークン取得で顧客のテナント 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 の使用#

1. 新しいコンソール アプリケーションを作成します。

2. NuGet Microsoft.Identity.Client をインストールします。

3. コードを使用して次を追加します。

    using Microsoft.Identity.Client;
   

   このコードは NuGet Microsoft.Identity.Clientでテストされました。

4. アプリケーションに次のコードをコピー/貼り付けます ( 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 の使用

1. コマンド ウィンドウを開きます。

2. CLIENT_IDを Azure アプリケーション ID に設定します。

3. CLIENT_SECRETを Azure アプリケーション シークレットに設定します。

4. TENANT_IDを、アプリケーションを使用して Microsoft Defender for Endpoint アプリケーションにアクセスする顧客の Azure テナント ID に設定します。

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

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

トークンを検証する

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

1. 前の手順で取得したトークンを JWT にコピー/貼り付けてデコードします。

2. 適切なアクセス許可を持つロール要求を取得することを確認します。

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

   

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

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

1. 使用する API を選択します。 詳細については、「 サポートされている Microsoft Defender for Endpoint API」を参照してください。

2. 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
• ユーザーの代わりに Microsoft Defender for Endpoint にアクセスする