ユーザー コンテキストMicrosoft Defender for Cloud Apps API にアクセスする
このページでは、ユーザーの代わりにプログラムからDefender for Cloud Appsにアクセスするためのアプリケーションを作成する方法について説明します。
ユーザーなしでプログラムによるアクセスMicrosoft Defender for Cloud Appsが必要な場合は、「アプリケーション コンテキストを使用したアクセスMicrosoft Defender for Cloud Apps」を参照してください。
必要なアクセスが不明な場合は、 概要ページを参照してください。
Microsoft Defender for Cloud Appsは、一連のプログラム API を通じて、そのデータとアクションの多くを公開します。 これらの API を使用すると、作業フローを自動化し、Microsoft Defender for Cloud Apps機能に基づいてイノベーションを行うことができます。 API アクセスには OAuth2.0 認証が必要です。 詳細については、「 OAuth 2.0 承認コード フロー」を参照してください。
一般に、API を使用するには、次の手順を実行する必要があります。
- Microsoft Entra アプリケーションを作成する
- このアプリケーションを使用してアクセス トークンを取得する
- トークンを使用して API にアクセスDefender for Cloud Apps
このページでは、Microsoft Entra アプリケーションを作成し、アクセス トークンを取得してMicrosoft Defender for Cloud Appsし、トークンを検証する方法について説明します。
注:
ユーザーの代わりに api Microsoft Defender for Cloud Appsアクセスする場合は、適切なアプリケーションのアクセス許可とユーザーのアクセス許可が必要です。 Microsoft Defender for Cloud Appsに対するユーザーのアクセス許可に慣れていない場合は、「管理者アクセスの管理」を参照してください。
ヒント
ポータルでアクションを実行するアクセス許可がある場合は、API でアクションを実行するアクセス許可があります。
アプリを作成する
Microsoft Entra 管理センターで、新しいアプリケーションを登録します。 詳細については、「クイック スタート: アプリケーションをMicrosoft Entra 管理センターに登録する」を参照してください。
[アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。
[名前 ] - アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します。
サポートされているアカウントの種類 - アプリケーションでサポートするアカウントを選択します。
サポートされているアカウントの種類 説明 この組織のディレクトリ内のアカウントのみ 基幹業務 (LOB) アプリケーションを作成している場合は、このオプションを選択します。 このオプションは、アプリケーションをディレクトリに登録していない場合は使用できません。
このオプションは、Microsoft Entra専用のシングルテナントにマップされます。
これは、ディレクトリの外部にアプリを登録している場合を除き、既定のオプションです。 アプリがディレクトリの外部に登録されている場合、既定値はマルチテナントおよび個人用の Microsoft アカウントMicrosoft Entraされます。組織のディレクトリ内のアカウント 企業および教育機関のすべてのユーザーを対象とする場合は、このオプションを選択します。
このオプションは、Microsoft Entra専用マルチテナントにマップされます。
アプリをMicrosoft Entra専用のシングルテナントとして登録した場合は、マルチテナントMicrosoft Entraに更新し、[認証] ウィンドウを使用してシングルテナントに戻すことができます。組織のディレクトリ内のアカウントと個人用 Microsoft アカウント 最も広い範囲の顧客を対象とする場合は、このオプションを選択します。
このオプションは、マルチテナントおよび個人用の Microsoft アカウントMicrosoft Entraにマップされます。
マルチテナントおよび個人用の Microsoft アカウントMicrosoft Entraとしてアプリを登録した場合、UI でこれを変更することはできません。 代わりに、アプリケーション マニフェスト エディターを使用して、サポートされているアカウントの種類を変更する必要があります。リダイレクト URI (省略可能) - ビルドするアプリの種類 **Web、または パブリック クライアント (モバイル & デスクトップ) を選択し、アプリケーションのリダイレクト URI (または応答 URL) を入力します。
- Web アプリケーションの場合は、アプリのベース URL を指定します。 たとえば、
http://localhost:31544はローカル マシンで実行されている Web アプリの URL になる場合があります。 ユーザーはこの URL を使用して、Web クライアント アプリケーションにサインインします。 - パブリック クライアント アプリケーションの場合は、トークン応答を返すためにMicrosoft Entra IDによって使用される URI を指定します。
myapp://authなどのアプリケーションに固有の値を入力します。
Web アプリケーションまたはネイティブ アプリケーションの具体的な例を見るには、「クイック スタート」を参照してください。
終了したら、[登録] を選択します。
- Web アプリケーションの場合は、アプリのベース URL を指定します。 たとえば、
アプリケーションがMicrosoft Defender for Cloud Appsにアクセスし、"アラートの読み取り" アクセス許可を割り当てることを許可します。
アプリケーション ページで[API のアクセス許可]、[アクセス許可の追加>>AP]を選択します。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 を書き留めます。
アプリケーション ページで、[ 概要 ] に移動し、次の情報をコピーします。
サポートされているアクセス許可スコープ
| アクセス許可名 | 説明 | サポートされているアクション |
|---|---|---|
| Investigation.read | 閉じるアラートを除き、アクティビティとアラートに対してサポートされているすべてのアクションを実行します。 IP 範囲を表示しますが、追加、更新、または削除は行いません。 すべてのエンティティ アクションを実行します。 |
アクティビティの一覧、フェッチ、フィードバック アラートの一覧、フェッチ、開封済み/未読としてマークする エンティティの一覧、フェッチ、フェッチ ツリー サブネットの一覧 |
| Investigation.manage | アラートと IP 範囲の管理に加えて、すべての investigation.read アクションを実行します。 | アクティビティの一覧、フェッチ、フィードバック アラートの一覧、フェッチ、読み取り/未読としてマーク、閉じる エンティティの一覧、フェッチ、フェッチ ツリー サブネットの一覧、作成、更新、削除 |
| Discovery.read | 閉じるアラートを除き、アクティビティとアラートに対してサポートされているすべてのアクションを実行します。 検出レポートとカテゴリを一覧表示します。 |
アラートの一覧、フェッチ、開封済み/未読としてマークする 検出リスト レポート、リスト レポート カテゴリ |
| Discovery.manage | Discovery.read アクセス許可 アラートを閉じ、検出ファイルをアップロードし、ブロック スクリプトを生成する |
アラートの一覧、フェッチ、読み取り/未読としてマーク、閉じる 検出リスト レポート、リスト レポート カテゴリ 検出ファイルのアップロード、ブロック スクリプトの生成 |
| Settings.read | IP 範囲を一覧表示します。 | サブネットの一覧 |
| Settings.manage | IP 範囲の一覧表示と管理。 | サブネットの一覧、作成、更新、削除 |
アクセス トークンを取得する
Microsoft Entra トークンの詳細については、「Microsoft Entra チュートリアル」を参照してください。
C の使用#
- アプリケーションで次のクラスをコピー/貼り付けます。
- アプリケーション ID、テナント ID、認証で AcquireUserTokenAsync メソッドを使用してトークンを取得します。
注:
次のコード サンプルでは、ユーザー名とパスワード フローを使用してトークンを取得する方法を示していますが、運用環境でより安全な認証フローを使用することをお勧めします。
namespace MDA
{
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;
public static class MDAUtils
{
private const string Authority = "https://login.microsoftonline.com";
private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
private const string Scope = "Investigation.read";
public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
{
using (var httpClient = new HttpClient())
{
var urlEncodedBody = $"scope={MDAId}/{Scope}&client_id={appId}&grant_type=password&username={username}&password={password}";
var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
{
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
var jObject = JObject.Parse(json);
return jObject["access_token"].Value<string>();
}
}
}
}
}
トークンを検証する
正しいトークンが取得されていることを確認します。
前の手順で取得したトークンを JWT にコピー/貼り付けてデコードする
目的のアプリのアクセス許可を持つ "scp" 要求を取得することを検証します
次のスクリーンショットでは、チュートリアルでアプリから取得したデコードされたトークンを確認できます。
トークンを使用してMicrosoft Defender for Cloud Apps API にアクセスする
使用する API を選択します。 詳細については、「Defender for Cloud Apps API」を参照してください。
送信する HTTP 要求の Authorization ヘッダーを "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