アプリケーション コンテキストを使って Microsoft Defender for Cloud Apps にアクセスする
このページでは、ユーザーなしで、Defender for Cloud Apps にプログラムでアクセスするアプリケーションを作成する方法について説明します。 ユーザーに代わって Defender for Cloud Apps にプログラムでアクセスする必要がある場合は、「ユーザー コンテキストを使用してアクセスする」を参照してください。 どちらのアクセスが必要かはっきりしない場合は、「API トークンの管理」ページを参照してください。
Microsoft Defender for Cloud Apps では、一連のプログラム API を使用して、そのデータとアクションの多くが公開されます。 これらの API は、Defender for Cloud Apps の機能に基づくワークフローの自動化およびイノベーションに役立ちます。 API アクセスには、OAuth2.0 認証が必要です。 詳細については、「OAuth 2.0 承認コード・フロー」に関するセクションを参照してください。
一般に、API を使用するには、次の手順を実行する必要があります。
- Microsoft Entra アプリケーションを作成します。
- このアプリケーションを使用してアクセス トークンを取得します。
- トークンを使用して Defender for Cloud Apps API にアクセスします。
この記事では、Microsoft Entra アプリケーションを作成し、Microsoft Defender for Cloud Apps へのアクセス トークンを取得して、トークンを検証する方法について説明します。
アプリを作成する
グローバル管理者ロールを持つユーザーを使用して、Azure にサインインします。
[Microsoft Entra ID]>[アプリの登録]>[新規登録] の順に移動します。
登録フォームで、アプリケーションの名前を選択し、[登録] を選択します。
アプリが Defender for Cloud Apps にアクセスできるようにし、[Read all alerts]\(すべてのアラートの読み取り\) アクセス権限を割り当てるには、アプリケーション ページで、[API のアクセス許可]>[アクセス許可の追加]>[所属する組織で使用している API]> の順に選択し、「Microsoft Cloud App Security」と入力してから、[Microsoft Cloud App Security] を選びます。
Note
Microsoft Cloud App Security は元の一覧には表示されません。 まず、テキスト ボックスにその名前を入力して、表示されることを確認してください。 製品が Defender for Cloud Apps と呼ばれていても、この名前を入力してください。
[アプリケーションのアクセス許可]>[Investigation.Read] の順に選んで、[アクセス許可の追加] を選択します。
関連するアクセス許可を選択する必要があります。 Investigation.Read は一例です。 その他のアクセス許可スコープについては、「サポートされているアクセス許可スコープ」を参照してください
- 必要なアクセス許可を確認するには、呼び出す API の [アクセス許可] セクションを表示します。
[管理者の同意の付与] を選択します。
Note
アクセス許可を追加するたびに、[管理者の同意の付与] を選択して新しいアクセス許可を有効にする必要があります。
アプリケーションにシークレットを追加するには、[証明書とシークレット] を選択し、[新しいクライアント シークレット] を選択し、シークレットの説明を追加してから、[追加] を選択します。
Note
[追加] を選択した後で、[copy the generated secret value]\(生成されたシークレット値をコピーする\) を選択します。 移動すると、この値は取得できなくなります。
アプリケーション ID とテナント ID を書き留めます。 アプリケーション ページで、[概要] に移動し、[アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] をコピーします。
Microsoft Defender for Cloud Apps パートナーのみ。 アプリをマルチテナントになるように設定します (同意後、すべてのテナントで使用できます)。 これは、サードパーティ アプリでは必須です (たとえば、複数の顧客のテナントで実行する予定のアプリを作成する場合)。 自分のテナントのみで実行するサービスを作成する場合、これは必須ではありません (たとえば、自分のデータのみを操作するアプリケーションを自分で使用するために作成する場合)。 アプリをマルチテナントになるように設定するには:
[認証] に移動し、
https://portal.azure.comを [リダイレクト URI] として追加します。ページの下部にある [サポートされているアカウントの種類] の下で、マルチテナント アプリのアプリケーション同意として [任意の組織のディレクトリ内のアカウント] を選択します。
使用する各テナント内で、アプリケーションを承認する必要があります。 これは、アプリケーションが顧客に代わって Defender for Cloud Apps を操作するためです。
あなた (またはサードパーティ アプリを作成している場合は顧客) は、同意リンクを選択してアプリを承認する必要があります。 同意は、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 で置き換えられます。
準備完了! アプリケーションが正常に登録されました。 トークンの取得と検証については、次の例を参照してください。
サポートされているアクセス許可スコープ
| 権限名 | 説明 | サポートされているアクション |
|---|---|---|
| Investigation.read | アラートを閉じる以外の、アクティビティとアラートに対してサポートされているアクションを実行します。 IP 範囲を表示しますが、追加、更新、削除は行いません。 すべてのエンティティ アクションを実行します。 |
アクティビティの一覧、フェッチ、フィードバック アラートの一覧、フェッチ、読み取り/未読としてマーク エンティティの一覧、フェッチ、ツリーのフェッチ サブネットの一覧 |
| Investigation.manage | アラートと IP 範囲の管理に加え、すべての investigation.read アクションを実行します。 | アクティビティの一覧、フェッチ、フィードバック アラートの一覧、フェッチ、読み取り/未読としてマーク、閉じる エンティティの一覧、フェッチ、ツリーのフェッチ サブネットの一覧、作成、更新、削除 |
| Discovery.read | アラートを閉じる以外の、アクティビティとアラートに対してサポートされているアクションを実行します。 検出レポートとカテゴリを一覧表示します。 |
アラートの一覧、フェッチ、読み取り/未読としてマーク 検出一覧のレポート、レポート カテゴリの一覧表示 |
| Discovery.manage | Discovery.read のアクセス許可 アラートを閉じ、検出ファイルをアップロードし、ブロック スクリプトを生成します |
アラートの一覧、フェッチ、読み取り/未読としてマーク、閉じる 検出一覧のレポート、レポート カテゴリの一覧表示 検出ファイルのアップロード、ブロック スクリプトの生成 |
| Settings.read | IP 範囲を一覧表示します。 | サブネットの一覧 |
| Settings.manage | IP 範囲を一覧表示および管理します。 | サブネットの一覧、作成、更新、削除 |
アクセス トークンを取得する
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
$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$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
C# を使用する
次のコードは、NuGet Microsoft.Identity.Client 4.47.2 を使用してテストされました。
新しいコンソール アプリケーションを作成します。
NuGet Microsoft.Identity.Client をインストールします。
以下を追加します。
using Microsoft.Identity.Client;次のコードをコピーしてアプリに貼り付けます (3 つの変数
tenantId, appId, appSecretの更新を忘れないでください)。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 = "05a65629-4c1b-48c1-a78b-804c4abdd4af"; IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build(); List scopes = new List() { $"{audience}/.default" }; AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult(); string token = authResult.AccessToken;
Python の使用
「Python 用の Microsoft Authentication Library (MSAL)」を参照してください。
Curl を使用する
Note
次の手順では、Curl for Windows がコンピューターに既にインストールされていることを前提とします。
- コマンド プロンプトを開き、CLIENT_ID を Azure アプリケーション ID に設定します。
- CLIENT_SECRET を Azure アプリケーション シークレットに設定します。
- TENANT_ID を、Defender for Cloud Apps にアクセスするためにアプリを使用する顧客の 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=05a65629-4c1b-48c1-a78b-804c4abdd4af/.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 に貼り付けて、デコードします。
- 必要なアクセス許可を含む "roles" クレームを取得していることを検証します。
- 次の画像では、アプリから取得してデコードしたトークンに、すべての Microsoft Defender for Cloud Apps ロールに対するアクセス許可があることを確認できます。
トークンを使用して Microsoft Defender for Cloud Apps API にアクセスする
- 使用する API を選びます。 詳細については、「Defender for Cloud Apps API」を参照してください。
- 送信する HTTP 要求の Authorization ヘッダーを "Bearer {token}" に設定します (Bearer は承認スキームです)。
- トークンの有効期限は 1 時間です。 同じトークンで複数の要求を送信できます。
次に示すのは、C# を使用してアラートの一覧を取得する要求を送信する例です。
var httpClient = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
// Do something useful with the response