Microsoft Defender for Endpoint API を使用したパートナー アクセス
適用対象:
- Microsoft Defender for Endpoint Plan 1
- Microsoft Defender for Endpoint Plan 2
- Microsoft Defender for Business
重要
高度なハンティング機能は、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
このページでは、Microsoft Entra アプリケーションを作成して、顧客に代わってMicrosoft Defender for Endpointにプログラムでアクセスする方法について説明します。
Microsoft Defender for Endpointは、一連のプログラム API を通じて、そのデータとアクションの多くを公開します。 これらの API は、Microsoft Defender for Endpoint機能に基づいて作業フローを自動化し、イノベーションを行うのに役立ちます。 API アクセスには OAuth2.0 認証が必要です。 詳細については、「 OAuth 2.0 承認コード フロー」を参照してください。
一般に、API を使用するには、次の手順を実行する必要があります。
マルチテナント Microsoft Entra アプリケーションを作成します。
顧客管理者が、必要な Defender for Endpoint リソースにアクセスするためのアプリケーションの承認 (同意) を取得します。
このアプリケーションを使用してアクセス トークンを取得します。
トークンを使用して、Microsoft Defender for Endpoint API にアクセスします。
次の手順では、Microsoft Entra アプリケーションを作成し、アクセス トークンを取得してトークンをMicrosoft Defender for Endpointし、検証する方法について説明します。
重要
Microsoft では、アクセス許可が可能な限りで少ないロールを使用することをお勧めします。 これにより、組織のセキュリティが向上します。 グローバル管理者は高い特権を持つロールであり、既存のロールを使用できない場合の緊急時に限定する必要があります。
マルチテナント アプリを作成する
Azure テナントにサインインします。
[Microsoft Entra ID>アプリの登録>新しい登録] に移動します。
登録フォームで、次の手順を実行します。
アプリケーションの名前を選択します。
サポートされているアカウントの種類 - 任意の組織のディレクトリ内のアカウント。
リダイレクト URI - 型: Web、URI: https://portal.azure.com
アプリケーションがMicrosoft Defender for Endpointにアクセスし、統合を完了するために必要な最小限のアクセス許可セットを割り当てることができるようにします。
API のアクセス許可を要求する
必要なアクセス許可を確認するには、呼び出す API の [アクセス許可] セクションを確認します。 例:
次の例では、 すべてのアラートの読み取り アクセス許可を使用します。
[アプリケーションのアクセス許可] を選択>Alert.Read.All>[アクセス許可の追加] を選択します
[ 同意の付与] を選択します
- アクセス許可を追加するたびに、[新しいアクセス許可を有効にするために 同意を付与 する] を選択する必要があります。
アプリケーションにシークレットを追加します。
- [ 証明書 & シークレット] を選択し、シークレットに説明を追加し、[ 追加] を選択します。
[追加] を選択したら、生成されたシークレット値を必ずコピーしてください。 退出後は取得できません。
アプリケーション ID を書き留めます。
アプリケーションを顧客のテナントに追加します。
アプリケーションを使用する各顧客テナントでアプリケーションを承認する必要があります。 この承認は、アプリケーションが顧客に代わってMicrosoft Defender for Endpointアプリケーションと対話するため必要です。
顧客のテナントに適切なアクセス許可を持つユーザー アカウントは、同意リンクを選択し、アプリケーションを承認する必要があります。
同意リンクは次の形式です。
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 を使用します。
Microsoft Entra トークンの詳細については、「Microsoft Entra チュートリアル」を参照してください。
PowerShell の使用
# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).
$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here
$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
resource = "$resourceAppIdUri"
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
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token
C の使用#
重要
Microsoft.IdentityModel.Clients.ActiveDirectory NuGet パッケージとAzure AD Authentication ライブラリ (ADAL) は非推奨になりました。 2020 年 6 月 30 日以降、新機能は追加されていません。 アップグレードするには、 移行ガイドを参照してください。
新しいコンソール アプリケーションを作成します。
コードを使用して次を追加します。
using Microsoft.Identity.Client;
このコードは NuGet
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
アプリケーションを使用してアプリケーションにアクセスする顧客の Azure テナント ID Microsoft Defender for Endpoint設定します。次のコマンドを実行します。
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する複数のアクセス許可を持つアプリケーションから取得されたデコードされたトークンを確認できます。
"tid" 要求は、トークンが属するテナント ID です。
トークンを使用して API にアクセスMicrosoft Defender for Endpoint
使用する API を選択します。 詳細については、「サポートされているMicrosoft Defender for Endpoint API」を参照してください。
Bearer {token}
に送信する Http 要求で Authorization ヘッダーを設定します (ベアラーは承認スキームです)。 トークンの有効期限は 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
関連項目
ヒント
さらに多くの情報を得るには、 Tech Community 内の Microsoft Security コミュニティ (Microsoft Defender for Endpoint Tech Community) にご参加ください。