次の方法で共有

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

  • [アーティクル]

適用対象:

  • Microsoft Defender XDR

重要

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

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

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

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

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

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

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

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

注:

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

ヒント

ポータルでアクションを実行するアクセス許可がある場合は、API でアクションを実行するアクセス許可があります。 ロールとアクセス許可の詳細については、「グローバル ロールを使用してMicrosoft Defender XDRへのアクセスMicrosoft Entra管理する」を参照してください。

アプリを作成する

  1. Azure にサインインします。

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

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

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

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

  4. アプリケーション ページで、[API のアクセス許可]>、[アクセス許可の追加>AP 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.All、 Incidents.ReadWrite.All、 AdvancedHunting.Read.All のアクセス許可で確認できます。

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

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

  1. 使用する API (インシデント、または高度なハンティング) を選択します。 詳細については、「サポートされているMicrosoft Defender XDR API」を参照してください。
  2. 送信しようとしている http 要求で、承認ヘッダーを "Bearer" <token> に設定し、 Bearer を承認スキームに、 トークン を検証済みトークンに設定します。
  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 Security コミュニティにご参加ください: 「Microsoft Defender XDR Tech Community」。