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

[アーティクル]
08/22/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 にアクセスできるようにし、[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 = "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 を使用する

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

次の方法で共有

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

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

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

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

PowerShell の使用

C# を使用する

Python の使用

Curl を使用する

トークンを検証する

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

関連項目

フィードバック

その他のリソース

次の方法で共有

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

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

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

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

PowerShell の使用

C# を使用する

Python の使用

Curl を使用する

トークンを検証する

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

関連項目

フィードバック

その他のリソース

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

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