ユーザーなしでMicrosoft Defender XDRにアクセスするアプリを作成する

適用対象:

• Microsoft Defender XDR

重要

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

このページでは、定義されたユーザーなしでMicrosoft Defender XDRにプログラムからアクセスするアプリケーションを作成する方法について説明します (たとえば、デーモンまたはバックグラウンド サービスを作成している場合)。

1 人以上のユーザーに代わってMicrosoft Defender XDRにプログラムでアクセスする必要がある場合は、「ユーザーの代わりにMicrosoft Defender XDR API にアクセスするアプリを作成する」および「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へのアクセス トークンを取得する
• トークンを検証します。

アプリを作成する

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

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

   

3. フォームで、アプリケーションの名前を選択し、[ 登録] を選択します。

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 パートナーのみ: Microsoft Defender XDR API を介したパートナー アクセスの手順に従い、アプリをマルチテナントに設定して、管理者の同意を受けたらすべてのテナントで使用できるようにします。 パートナー アクセスはサード パーティ製アプリに 必要 です。たとえば、複数の顧客のテナントで実行することを目的としたアプリを作成する場合などです。 テナントでのみ実行するサービス (独自のデータとのみ対話する独自の使用状況のアプリケーションなど) を作成する場合は 必要ありません 。 アプリをマルチテナントに設定するには:

   • [認証] に移動し、[リダイレクト URI] としてhttps://portal.azure.comを追加します。

   • ページの下部にある [ サポートされているアカウントの種類] で、マルチテナント アプリに対する 任意の組織ディレクトリ アプリケーションの同意のアカウント を選択します。

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

   各テナントの Active Directory 管理者は、同意リンクを選択してアプリを承認する必要があります。

   同意リンクの構造は次のとおりです。

   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 に置き換える必要があります。

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

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

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

重要

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

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, such as the Azure Key Vault!

$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 つの変数を更新することを忘れないでください)。

   csharp
   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://api.security.microsoft.com/.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> に設定し、 ベアラー を承認スキームに、 トークン を検証済みトークンに設定します。

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 API にアクセスするアプリを作成する
• Microsoft Defender XDR API へのマルチテナント パートナー アクセス権を持つアプリを作成する
• API の制限とライセンスについて説明します
• エラー コードについて
• Azure Key Vaultを使用してサーバー アプリのシークレットを管理する
• ユーザー サインインと API アクセスに対する OAuth 2.0 承認

ヒント

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