Microsoft Defender for Endpoint API を使用する

このページでは、ユーザーの代わりに 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 アプリケーションを作成する
• このアプリケーションを使用してアクセス トークンを取得する
• トークンを使用して Defender for Endpoint API にアクセスする

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

アプリを作成する

1. Azure portal にサインインし

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 のアクセス許可]、[>]、[アクセス許可の追加>AP organizationで使用します>「WindowsDefenderATP」と入力し、WindowsDefenderATP を選択します。

     注:

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

     

   • [委任されたアクセス許可] を選択>Alert.Read> [アクセス許可の追加] を選択します。

     

   重要

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

   例:

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

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

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

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

     注:

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

     

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

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

   

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

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

C の使用#

この例では、Microsoft Authentication Library(MSAL)を使ってトークンをインタラクティブに取得します。 実行する前に:

• Microsoft.Identity.Client NuGet パッケージをプロジェクトに追加します。
• アプリ登録時に、リダイレクトURIを使ったhttp://localhostプラットフォームを設定し、インタラクティブフローがトークンを返すようにしてください。
• 次のクラスをアプリケーションにコピー&ペーストし、アプリケーションIDとテナントIDで AcquireUserTokenAsync を呼び出します。 ユーザーはインタラクティブにサインインするよう促されます。彼らのパスワードはあなたのアプリケーションによって決して処理されません。

    namespace WindowsDefenderATP
    {
        using System.Linq;
        using System.Threading.Tasks;
        using Microsoft.Identity.Client;

        public static class WindowsDefenderATPUtils
        {
            private const string Authority = "https://login.microsoftonline.com";

            // Microsoft Defender for Endpoint APIs expect tokens issued for this resource.
            private static readonly string[] Scopes = { "https://api.securitycenter.microsoft.com/.default" };

            public static async Task<string> AcquireUserTokenAsync(string appId, string tenantId)
            {
                // Public client application for a native (desktop) app.
                // No client secret or user password is stored or handled by the app.
                var app = PublicClientApplicationBuilder
                    .Create(appId)
                    .WithAuthority($"{Authority}/{tenantId}")
                    .WithDefaultRedirectUri() // http://localhost - register as a public client redirect URI
                    .Build();

                var account = (await app.GetAccountsAsync().ConfigureAwait(false)).FirstOrDefault();

                try
                {
                    // Reuse a cached token when one is available.
                    var silentResult = await app
                        .AcquireTokenSilent(Scopes, account)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return silentResult.AccessToken;
                }
                catch (MsalUiRequiredException)
                {
                    // First run or expired session: prompt the user to sign in.
                    // Uses the authorization code flow with PKCE and supports
                    // multifactor authentication and Conditional Access.
                    var interactiveResult = await app
                        .AcquireTokenInteractive(Scopes)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return interactiveResult.AccessToken;
                }
            }
        }
    }

トークンを検証する

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

• 前の手順で取得したトークンを 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.security.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にアクセスする