Microsoft Defender XDR API へのパートナー アクセス権を持つアプリを作成する

適用対象:

• Microsoft Defender XDR

重要

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

このページでは、複数のテナント間のユーザーに代わって、Microsoft Defender XDRへのプログラムによるアクセス権を持つMicrosoft Entra アプリを作成する方法について説明します。 マルチテナント アプリは、大規模なユーザー グループにサービスを提供するのに役立ちます。

1 人のユーザーに代わってMicrosoft Defender XDRにプログラムでアクセスする必要がある場合は、「ユーザーの代わりにMicrosoft Defender XDR API にアクセスするためのアプリの作成」を参照してください。 ユーザーを明示的に定義せずにアクセスする必要がある場合 (たとえば、バックグラウンド アプリやデーモンを作成している場合)、「ユーザーなしでMicrosoft Defender XDRにアクセスするためのアプリの作成」を参照してください。 必要なアクセスの種類がわからない場合は、「 概要」を参照してください。

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へのアクセス トークンを取得する
• トークンを検証する

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

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

• マルチテナント Microsoft Entra アプリケーションを作成します。
• アプリケーションが必要なリソースにアクセスするために、ユーザー管理者によって承認 (同意)Microsoft Defender XDR取得します。
• このアプリケーションを使用してアクセス トークンを取得します。
• トークンを使用して、Microsoft Defender XDR API にアクセスします。

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

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

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

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

   

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

   • アプリケーションの名前を選択します。
   • [サポートされているアカウントの種類] で、[任意の組織のディレクトリ (任意のMicrosoft Entra ディレクトリ)] - [マルチテナント] の順に選択します。
   • [リダイレクト URI] セクションに入力します。 [ Web ] の種類を選択し、リダイレクト URI を https://portal.azure.comとして指定します。

   フォームへの入力が完了したら、[ 登録] を選択します。

   

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

   ヒント

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

   

5. [アプリケーションのアクセス許可] を選択します。 シナリオに関連するアクセス許可 ( Incident.Read.All など) を選択し、[ アクセス許可の追加] を選択します。

   

   注:

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

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

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

   

7. アプリケーションにシークレットを追加するには、[ 証明書 & シークレット] を選択し、シークレットに説明を追加してから、[ 追加] を選択します。

   ヒント

   [ 追加] を選択した後、[ 生成されたシークレット値のコピー] を選択します。 脱退後にシークレット値を取得することはできません。

   

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

   

9. アプリケーションをユーザーのテナントに追加します。

   アプリケーションはユーザーに代わってMicrosoft Defender XDRと対話するため、使用するすべてのテナントに対して承認する必要があります。

   ユーザーのテナントの管理者は、同意リンクを表示し、アプリケーションを承認する必要があります。

   同意リンクは次の形式です。

   https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
   

   00000000-0000-0000-0000-000000000000数字は、アプリケーション ID に置き換える必要があります。

   同意リンクをクリックした後、ユーザーのテナントの管理者としてサインインし、アプリケーションに同意を付与します。

   

   また、ユーザーにテナント ID の入力を求める必要もあります。 テナント ID は、アクセス トークンの取得に使用される識別子の 1 つです。

• 完了! アプリケーションが正常に登録されました。
• トークンの取得と検証については、以下の例を参照してください。

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

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

重要

このセクションの例では、テスト目的でシークレット値を貼り付けることをお勧めしますが、運用環境で実行されているアプリケーションに シークレットをハードコーディングしないでください 。 サード パーティは、シークレットを使用してリソースにアクセスできます。 Azure Key Vaultを使用して、アプリのシークレットを安全に保つことができます。 アプリを保護する方法の実際の例については、「Azure Key Vaultを使用してサーバー アプリのシークレットを管理する」を参照してください。

ヒント

次の例では、ユーザーのテナント ID を使用して、スクリプトが動作していることをテストします。

PowerShell を使用してアクセス トークンを取得する

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    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 3.19.8 でテストされました。

重要

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

1. 新しいコンソール アプリケーションを作成します。

2. NuGet Microsoft.Identity.Client をインストールします。

3. 次の行を追加します。

   using Microsoft.Identity.Client;
   

4. 次のコードをコピーしてアプリに貼り付けます ( tenantId、 clientId、 appSecretの 3 つの変数を更新することを忘れないでください)。

   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 を使用してアクセス トークンを取得する

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

curl を使用してアクセス トークンを取得する

注:

Curl は、バージョン 1803 以降のWindows 10にプレインストールされています。 他のバージョンの Windows の場合は、 公式の curl Web サイトから直接ツールをダウンロードしてインストールします。

1. コマンド プロンプトを開き、CLIENT_IDを Azure アプリケーション ID に設定します。
2. CLIENT_SECRETを Azure アプリケーション シークレットに設定します。
3. TENANT_IDを、アプリを使用してMicrosoft Defender XDRにアクセスするユーザーの Azure テナント ID に設定します。
4. 次のコマンドを実行します。

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. トークンをコピーして JSON Web トークン検証コントロール Web サイト JWT に貼り付けてデコードします。
2. デコードされたトークン内の ロール 要求に必要なアクセス許可が含まれていることを確認します。

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

トークンを使用して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();

関連記事

• Microsoft Defender XDR API の概要
• Microsoft Defender XDR API にアクセスする
• 'Hello world' アプリケーションを作成する
• ユーザーなしでMicrosoft Defender XDRにアクセスするアプリを作成する
• ユーザーの代わりにMicrosoft Defender XDR API にアクセスするアプリを作成する
• API の制限とライセンスについて説明します
• エラー コードについて
• Azure Key Vaultを使用してサーバー アプリのシークレットを管理する
• ユーザー サインインと API アクセスに対する OAuth 2.0 承認

ヒント

さらに多くの情報を得るには、 Tech Community 内の Microsoft Security コミュニティにご参加ください: 「Microsoft Defender XDR Tech Community」。