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

[アーティクル]
11/19/2024

適用対象:

重要

高度なハンティング機能は、Defender for Businessには含まれていません。

Microsoft Defender ATP を試してみたいですか? 無料試用版にサインアップしてください。

注:

米国政府機関のお客様の場合は、米国政府機関のお客様のMicrosoft Defender for Endpointに記載されている URI を使用してください。

ヒント

パフォーマンスを向上させるために、地理的な場所に近いサーバーを使用できます。

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

このページでは、ユーザーなしで Defender for Endpoint にプログラムでアクセスするためのアプリケーションを作成する方法について説明します。ユーザーの代わりに Defender for Endpoint へのプログラムによるアクセスが必要な場合は、「ユーザーコンテキストを使用してアクセスを取得する」を参照してください。必要なアクセスが不明な場合は、「概要」を参照してください。

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

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

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

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

重要

Microsoft では、アクセス許可が可能な限りで少ないロールを使用することをお勧めします。これにより、組織のセキュリティが向上します。グローバル管理者は高い特権を持つロールであり、既存のロールを使用できない場合の緊急時に限定する必要があります。

アプリを作成する

Azure portal にサインインし
[Microsoft Entra ID>アプリの登録>新しい登録] に移動します。
登録フォームで、アプリケーションの名前を選択し、[ 登録] を選択します。
アプリが Defender for Endpoint にアクセスして "すべてのアラートの読み取り" アクセス許可を割り当てるには、アプリケーションページで [API のアクセス許可]、[アクセス許可の追加>>API]、[organizationで使用する API]、[>「WindowsDefenderATP」と入力し、[WindowsDefenderATP] を選択します。

注:

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

[ アプリケーションのアクセス許可>Alert.Read.All] を選択し、[ アクセス許可の追加] を選択します。
適切なアクセス許可を選択します。 Read All Alerts は一例にすぎません。次に、いくつかの例を示します:
- 高度なクエリを実行するには、Run advanced queriesアクセス許可を選択します。
- デバイスを分離するには、Isolate machineアクセス許可を選択します。
- 必要なアクセス許可を特定するには、呼び出す API の [アクセス許可] セクションを参照してください。
[ 同意の付与] を選択します。

注:

アクセス許可を追加するたびに、新しいアクセス許可を有効にするには、[ 同意の付与 ] を選択する必要があります。
アプリケーションにシークレットを追加するには、[ 証明書 & シークレット] を選択し、シークレットに説明を追加して、[ 追加] を選択します。

注:

[ 追加] を選択した後、[ 生成されたシークレット値のコピー] を選択します。退出後、この値を取得することはできません。
アプリケーション ID とテナント ID を書き留めます。アプリケーションページで、[ 概要 ] に移動し、次の内容をコピーします。
Microsoft Defender for Endpoint パートナーの場合のみ。アプリをマルチテナントに設定します (同意後、すべてのテナントで使用できます)。これは、サードパーティ製アプリに必要です (たとえば、複数の顧客のテナントで実行することを目的としたアプリを作成する場合)。これは、テナントでのみ実行するサービスを作成する場合は 必須ではありません (たとえば、独自のデータとのみ対話する独自の使用状況のアプリケーションを作成する場合)。アプリをマルチテナントに設定するには、次の手順に従います。
1. [認証] に移動し、[リダイレクト URI] としてhttps://portal.azure.comを追加します。
2. ページの下部にある [ サポートされているアカウントの種類] で、マルチテナントアプリに対する 任意の組織ディレクトリアプリケーションの同意のアカウント を選択します。
  
  アプリケーションを使用する予定の各テナントでアプリケーションを承認する必要があります。これは、アプリケーションが顧客の代わりに Defender for Endpoint と対話するためです。
  
  ユーザー (またはサードパーティ製アプリを作成している場合は顧客) は、同意リンクを選択してアプリを承認する必要があります。同意は、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 チュートリアルを参照してください。

PowerShell を使う

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$token

C#を使用する:

次のコードは、NuGet Microsoft.Identity.Client 3.19.8 でテストされました。

重要

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

新しいコンソールアプリケーションを作成します。
NuGet Microsoft.Identity.Client をインストールします。
次を追加します。
```
using Microsoft.Identity.Client;
```

次のコードをコピーしてアプリに貼り付けます ( tenantId, appId, 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 を使用する

「Python を使用してトークンを取得する」を参照してください。

Curl を使用する

注:

次の手順では、Curl for Windows がコンピューターに既にインストールされていることを前提としています。

コマンドプロンプトを開き、 CLIENT_ID を Azure アプリケーション ID に設定します。
CLIENT_SECRETを Azure アプリケーションシークレットに設定します。
TENANT_IDを、アプリを使用して Defender for Endpoint にアクセスする顧客の Azure テナント ID に設定します。

次のコマンドを実行します。

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"}

トークンを検証する

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

前の手順で取得したトークンをコピーして JWT に貼り付けてデコードします。
目的のアクセス許可を持つロール要求を取得することを検証します。

次の図では、Microsoft Defender for Endpointのすべてのロールに対するアクセス許可を持つアプリから取得したデコードされたトークンを確認できます。

トークンを使用して API にアクセスMicrosoft Defender for Endpoint

使用する API を選択します。詳細については、「サポートされている Defender for Endpoint API」を参照してください。
Bearer {token}に送信するhttp要求で承認ヘッダーを設定します (ベアラーは承認スキームです)。
トークンの有効期限は 1 時間です。同じトークンを使用して複数の要求を送信できます。

C # を使用してアラートの一覧を取得する要求を送信する例を次に示します。

var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.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にアクセスするアプリを作成する

アプリを作成する

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

PowerShell を使う

C#を使用する:

Python を使用する

Curl を使用する

トークンを検証する

トークンを使用して API にアクセスMicrosoft Defender for Endpoint

関連項目

フィードバック

その他のリソース

次の方法で共有

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

アプリを作成する

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

PowerShell を使う

C#を使用する:

Python を使用する

Curl を使用する

トークンを検証する

トークンを使用して API にアクセスMicrosoft Defender for Endpoint

関連項目

フィードバック

その他のリソース

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