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

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

ユーザーなしでプログラムによるアクセスMicrosoft Defender for Endpointが必要な場合は、「アプリケーション コンテキストを使用したアクセス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 API にアクセスする

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

注:

ユーザーの代わりに Microsoft Defender for Endpoint API にアクセスする場合は、適切なアプリケーションのアクセス許可とユーザーアクセス許可が必要です。 Microsoft Defender for Endpointに対するユーザーのアクセス許可に慣れていない場合は、「ロールベースのアクセス制御を使用してポータル アクセスを管理する」を参照してください。

ヒント

ポータルでアクションを実行するアクセス許可がある場合は、API でアクションを実行するアクセス許可があります。

アプリを作成する

1. グローバル管理者ロールを持つユーザー アカウントで Azure にログオンします。

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

   

3. [アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。

   • 名前 - アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します。

   • サポートされているアカウントの種類 - アプリケーションでサポートするアカウントを選択します。

     
     

     サポートされているアカウントの種類	説明
     この組織のディレクトリ内のアカウントのみ	基幹業務 (LOB) アプリケーションを作成している場合は、このオプションを選択します。 アプリケーションをディレクトリに登録していない場合、このオプションは選択できません。 このオプションは、Microsoft Entra専用のシングルテナントにマップされます。 これは、ディレクトリの外部にアプリを登録している場合を除き、既定のオプションです。 アプリがディレクトリの外部に登録されている場合、既定値はマルチテナントアカウントと個人用 Microsoft アカウントMicrosoft Entraです。
     組織のディレクトリ内のアカウント	企業および教育機関のすべてのユーザーを対象とする場合は、このオプションを選択します。 このオプションは、Microsoft Entra専用マルチテナントにマップされます。 アプリをMicrosoft Entra専用のシングルテナントとして登録した場合は、[認証] ブレードを使用して、マルチテナントMicrosoft Entraし、シングルテナントに戻すようにアプリを更新できます。
     組織のディレクトリ内のアカウントと個人用 Microsoft アカウント	最も広い範囲の顧客を対象とする場合は、このオプションを選択します。 このオプションは、マルチテナントと個人用の Microsoft アカウントMicrosoft Entraにマップされます。 アプリをマルチテナントアカウントと個人用 Microsoft アカウントMicrosoft Entra登録した場合、UI でこれを変更することはできません。 代わりに、アプリケーション マニフェスト エディターを使用して、サポートされているアカウントの種類を変更する必要があります。

   • リダイレクト URI (オプション) - 構築しているアプリの種類として Web または パブリック クライアント (モバイルとデスクトップ) を選択し、アプリケーションのリダイレクト URI (または応答 URL) を入力します。

     • Web アプリケーションの場合は、アプリのベース URL を指定します。 たとえば、http://localhost:31544 はローカル マシンで実行されている Web アプリの URL になる場合があります。 ユーザーはこの URL を使用して、Web クライアント アプリケーションにサインインします。

     • パブリック クライアント アプリケーションの場合は、トークン応答を返すためにMicrosoft Entra IDによって使用される URI を指定します。 myapp://auth などのアプリケーションに固有の値を入力します。

     Web アプリケーションまたはネイティブ アプリケーションの具体的な例を見るには、「クイック スタート」を参照してください。

     終了したら、[登録] を選択します。

4. アプリケーションがMicrosoft Defender for Endpointにアクセスし、"アラートの読み取り" アクセス許可を割り当てることを許可します。

   • アプリケーション ページで、[API アクセス許可][アクセス許可>>の追加] API を選択し、organizationがWindowsDefenderATP 型を使用>し、WindowsDefenderATP を選択します。

     注:

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

     

   • [ 委任されたアクセス許可>] [アラート]、[読み取り> ] の [ アクセス許可の追加] の順に選択します。

     

   重要

   関連するアクセス許可を選択します。 アラートの読み取りは一例にすぎません。

   以下に例を示します。

   • 高度なクエリを実行するには、[高度なクエリの実行] アクセス許可を選択します。

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

   • 必要なアクセス許可を決定するには、呼び出す API の [アクセス許可] セクションを表示します。

   • [ 同意の付与] を選択します。

     注:

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

     

5. アプリケーション ID とテナント ID を書き留めます。

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

   

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

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

C の使用#

• アプリケーションで以下のクラスをコピー/貼り付けます。

• トークンを取得するには、アプリケーション ID、テナント ID、ユーザー名、パスワードを使用して AcquireUserTokenAsync メソッドを使用します。

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

トークンを検証する

正しいトークンが取得されていることを確認します。

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

• 目的のアプリのアクセス許可を持つ "scp" 要求を取得したことを検証します。

• 次のスクリーンショットでは、チュートリアルでアプリから取得したデコードされたトークンを確認できます。

  

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

• 使用する API - サポートされているMicrosoft Defender for Endpoint API を選択します。

• 送信する 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) にご参加ください。