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

適用対象:

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

重要

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

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

注:

米国政府機関のお客様の場合は、米国政府機関のお客様のMicrosoft Defender for Endpointに記載されている 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

このページでは、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 アプリケーションをCreateします。
• 顧客管理者が、必要な Defender for Endpoint リソースにアクセスするためのアプリケーションの承認 (同意) を取得します。
• このアプリケーションを使用してアクセス トークンを取得します。
• トークンを使用して、Microsoft Defender for Endpoint API にアクセスします。

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

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

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

2. [Microsoft Entra ID>アプリの登録新しい登録]> に移動します。

   

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

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

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

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

     

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

   • アプリケーション ページで、[API アクセス許可][アクセス許可>>の追加] API を選択し、organizationが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
   

   ここで、000000000-0000-0000-0000000000000 はアプリケーション 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 の使用#

次のコードは、Nuget Microsoft.Identity.Client でテストされました

重要

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

• 新しいコンソール アプリケーションをCreateする

• NuGet Microsoft.Identity.Client をインストールする

• を使用して以下を追加します

  using Microsoft.Identity.Client;
  

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

  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 がコンピューターに既にインストールされていると想定されています

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

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

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

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

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 です。

   

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

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

2. 送信する Http 要求の Authorization ヘッダーを "Bearer {token}" に設定します (ベアラーは承認スキームです)。 トークンの有効期限は 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にアクセスする

ヒント

さらに多くの情報を得るには、 Tech Community 内の Microsoft Security コミュニティ (Microsoft Defender for Endpoint Tech Community) にご参加ください。