ユーザーの代わりにMicrosoft Defender XDR API にアクセスするアプリをCreateする

  • [アーティクル]

適用対象:

  • Microsoft Defender XDR

重要

一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関するものです。 Microsoft は、ここに記載された情報に関して、明示または黙示を問わず、いかなる保証も行いません。

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

ユーザーが定義されていないMicrosoft Defender XDRにプログラムでアクセスする必要がある場合 (たとえば、バックグラウンド アプリやデーモンを作成している場合)、ユーザーなしでMicrosoft Defender XDRにアクセスするには、アプリCreateに関するページを参照してください。 大規模なorganizationや顧客のグループにサービスを提供している場合など、複数のテナントに対してアクセス権を提供する必要がある場合は、「Microsoft Defender XDR API へのパートナー アクセス権を持つアプリCreate」を参照してください。必要なアクセスの種類がわからない場合は、「概要」を参照してください。

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

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

  • Microsoft Entra アプリケーションをCreateします。
  • このアプリケーションを使用してアクセス トークンを取得します。
  • トークンを使用して、Microsoft Defender XDR API にアクセスします。

この記事では、次の方法について説明します。

  • Microsoft Entra アプリケーションをCreateする
  • Microsoft Defender XDRへのアクセス トークンを取得する
  • トークンを検証する

注:

ユーザーの代わりに Microsoft Defender XDR API にアクセスする場合は、適切なアプリケーションのアクセス許可とユーザーのアクセス許可が必要です。

ヒント

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

アプリを作成する

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

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

    Azure portalの [管理] ウィンドウの [新しい登録] オプション

  3. フォームで、アプリケーションの名前を選択し、リダイレクト URI の次の情報を入力し、[ 登録] を選択します。

    Azure portalのアプリケーション登録ウィンドウ

  4. アプリケーション ページで、[API アクセス許可][アクセス許可>の追加] の順>に選択し、organizationが使用する API を選択>し、「Microsoft Threat Protection」と入力して、[Microsoft Threat Protection] を選択します。 アプリがMicrosoft Defender XDRにアクセスできるようになりました。

    ヒント

    Microsoft Threat Protection は、Microsoft Defender XDRの以前の名前であり、元の一覧には表示されません。 テキスト ボックスに名前を書き込んで表示する必要があります。

    Microsoft Defender ポータルのorganizationの API ペイン

    • [ 委任されたアクセス許可] を選択します。 シナリオに関連するアクセス許可 ( Incident.Read など) を選択し、[ アクセス許可の追加] を選択します。

      Microsoft Defender ポータルの [委任されたアクセス許可] ウィンドウ

    注:

    シナリオに関連するアクセス許可を選択する必要があります。 すべてのインシデントの読み取り は単なる例です。 必要なアクセス許可を決定するには、呼び出す API の [アクセス許可 ] セクションを参照してください。

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

  5. [ 管理者の同意の付与] を選択します。 アクセス許可を追加するたびに、[管理者の同意を 付与 する] を選択して有効にする必要があります。

    Microsoft Defender ポータルの管理者の同意許可ウィンドウ

  6. アプリケーション ID とテナント ID を安全な場所に記録します。 これらは、アプリケーション ページの [概要 ] の下に表示されます。

    Microsoft Defender ポータルの [概要] ウィンドウ

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

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

PowerShell を使用してユーザーの代わりにアクセス トークンを取得する

MSAL.PS ライブラリを使用して、委任されたアクセス許可を持つアクセス トークンを取得します。 次のコマンドを実行して、ユーザーの代わりにアクセス トークンを取得します。

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

トークンを検証する

  1. トークンをコピーして JWT に貼り付けてデコードします。
  2. デコードされたトークン内の ロール 要求に必要なアクセス許可が含まれていることを確認します。

次の図では、、、および アクセス許可を持つIncidents.Read.AllIncidents.ReadWrite.Allアプリから取得されたデコードされたトークンをAdvancedHunting.Read.All確認できます。

Microsoft Defender ポータルの [デコードされたトークン] ウィンドウの [アクセス許可] セクション

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

  1. 使用する API (インシデント、または高度なハンティング) を選択します。 詳細については、「サポートされているMicrosoft Defender XDR API」を参照してください。
  2. 送信しようとしている http 要求で、承認ヘッダーを に、ベアラーを"Bearer" <token>承認スキームに、トークンを検証済みトークンに設定します。
  3. トークンは 1 時間以内に期限切れになります。 この間、同じトークンを使用して複数の要求を送信できます。

次の例は、 C# を使用してインシデントの一覧を取得する要求を送信する方法を示しています。

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

ヒント

さらに多くの情報を得るには、 Tech Community: Microsoft Defender XDR Tech Community の Microsoft Security コミュニティとEngageします。