アプリケーションコンテキストを使用してMicrosoft Defender for Cloud Appsにアクセスする

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

このページでは、ユーザーなしで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へのアクセストークンを取得し、トークンを検証する方法について説明します。

Defender for Cloud Apps用のアプリを作成する

Microsoft Entra 管理センターで、新しいアプリケーションを登録します。詳細については、「クイックスタート: アプリケーションをMicrosoft Entra 管理センターに登録する」を参照してください。
アプリがDefender for Cloud Appsにアクセスして "すべてのアラートの読み取り" アクセス許可を割り当てるには、アプリケーションページで [API のアクセス許可の追加]、[アクセス許可の追加>>API]、[organizationで使用する API] の順に選択し>「Microsoft Cloud App Security」と入力し、[Microsoft] を選択します。Cloud App Security。

注:

Microsoft Cloud App Securityは元の一覧には表示されません。テキストボックスに名前を書き込み、表示されるようにします。製品が Defender for Cloud Apps と呼ばれるようになった場合でも、必ずこの名前を入力してください。
- [ アプリケーションのアクセス許可>Investigation.Read] を選択し、[ アクセス許可の追加] を選択します。
  
  関連するアクセス許可を選択する必要があります。 Investigation.Read は一例にすぎません。その他のアクセス許可スコープについては、「サポートされているアクセス許可スコープ」を参照してください。
  - 必要なアクセス許可を特定するには、呼び出す API の [アクセス許可] セクションを参照してください。
[ 管理者の同意の付与] を選択します。

注:

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

注:

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

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

string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // 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 を使用する

注:

次の手順では、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 に貼り付けてデコードします。
目的のアクセス許可を持つ "ロール" 要求を取得することを検証します
次の図では、すべてのMicrosoft Defender for Cloud Apps ロールへのアクセス許可を持つアプリから取得されたデコードされたトークンを確認できます。

トークン検証のスクリーンショット。

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

使用する API を選択します。詳細については、「Defender for Cloud Apps API」を参照してください。
送信する http 要求の承認ヘッダーを "Bearer {token}" に設定します (ベアラーは承認スキームです)。
トークンの有効期限は 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

次の方法で共有

アプリケーションコンテキストを使用してMicrosoft Defender for Cloud Appsにアクセスする

Defender for Cloud Apps用のアプリを作成する

サポートされているアクセス許可スコープ

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

PowerShell を使う

C を使用する#

Python を使用する

Curl を使用する

トークンを検証する

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

関連項目

フィードバック

その他のリソース

次の方法で共有

アプリケーション コンテキストを使用してMicrosoft Defender for Cloud Appsにアクセスする

Defender for Cloud Apps用のアプリを作成する

サポートされているアクセス許可スコープ

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

PowerShell を使う

C を使用する#

Python を使用する

Curl を使用する

トークンを検証する

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

関連項目

フィードバック

その他のリソース

アプリケーションコンテキストを使用してMicrosoft Defender for Cloud Appsにアクセスする

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