Share via

ユーザー コンテキストを使用して 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 アプリケーションを作成する
  • このアプリケーションを使用してアクセス トークンを取得する
  • トークンを使用して Defender for Cloud Apps API にアクセスする

このページでは、Microsoft Entra アプリケーションを作成し、Microsoft Defender for Cloud Apps へのアクセス トークンを取得して、トークンを検証する方法について説明します。

Note

ユーザーに代わって Microsoft Defender for Cloud Apps API にアクセスする場合は、適切なアプリケーションのアクセス許可とユーザーのアクセス許可が必要です。 Microsoft Defender for Cloud Apps のユーザー アクセス許可に慣れていない場合は、「管理者アクセスを管理する」を参照してください。

ヒント

ポータルでアクションを実行するアクセス許可がある場合、API でアクションを実行するアクセス許可があります。

アプリを作成する

  1. グローバル管理者ロールを持つユーザー アカウントを使用して、Azure にサインインします。

  2. [Microsoft Entra ID]>[アプリの登録]>[新規登録] の順に移動します。

    Image of Microsoft Azure and navigation to application registration.

  3. [アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。

    • [名前] - アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します。

    • [サポートされているアカウントの種類] - アプリケーションでサポートするアカウントを選択します。

      サポートされる勘定タイプ 説明
      この組織のディレクトリ内のアカウントのみ 基幹業務 (LOB) アプリケーションを作成している場合は、このオプションを選択します。 アプリケーションをディレクトリに登録していない場合、このオプションは選択できません。

      このオプションは、Microsoft Entra 専用のシングル テナントにマップされます。

      これは、ディレクトリの外部にアプリを登録している場合を除き、既定のオプションです。 アプリがディレクトリの外部に登録される場合、既定のオプションは Microsoft Entra マルチテナントと個人の Microsoft アカウントです。
      任意の組織のディレクトリ内のアカウント 企業および教育機関のすべてのユーザーを対象とする場合は、このオプションを選択します。

      このオプションは、Microsoft Entra 専用マルチテナントにマップされます。

      アプリを Microsoft Entra のみのシングルテナントとして登録した場合は、[認証] ペインを使用して、Microsoft Entra マルチテナントに更新し、シングルテナントに戻ることができます。
      任意の組織のディレクトリ内のアカウントと、個人用の Microsoft アカウント このオプションを選択して、最も幅広い顧客を対象にします。

      このオプションは、Microsoft Entra マルチテナントと個人用の Microsoft アカウントに対応します。

      アプリを Microsoft Entra マルチテナントと個人用の Microsoft アカウントとして登録した場合、UI でこれを変更することはできません。 代わりに、アプリケーション マニフェスト エディターを使用してサポートされているアカウント タイプを変更する必要があります。

    • [リダイレクト URI]\(オプション) - 構築しているアプリの種類として [Web] または [パブリック クライアント (モバイルとデスクトップ)] を選択してから、アプリケーションのリダイレクト URI (または応答 URL) を入力します。

      • Web アプリケーションの場合は、アプリのベース URL を指定します。 ローカル マシンで実行されている Web アプリの URL であれば、たとえば http://localhost:31544 のようになります。 ユーザーはこの URL を使用して、Web クライアント アプリケーションにサインインすることになります。
      • パブリック クライアント アプリケーションの場合は、トークン応答を返すために Microsoft Entra ID によって使用される URI を指定します。 アプリケーション固有の値 (たとえば、myapp://auth) を入力します。

      Web アプリケーションまたはネイティブ アプリケーションの具体的な例を見るには、クイック スタートを参照してください。

      終了したら、 [登録] を選択します。

  4. アプリケーションに Microsoft Defender for Cloud Apps へのアクセスを許可し、"アラートの読み取り" アクセス許可を割り当てます。

    • アプリケーション ページで、[API のアクセス許可]>[アクセス許可の追加]>[所属する組織で使用している API]> の順に選択し、「Microsoft Cloud App Security」と入力してから、[Microsoft Cloud App Security] を選びます。

    • 注: Microsoft Cloud App Security は元の一覧には表示されません。 まず、テキスト ボックスにその名前を入力して、表示されることを確認してください。 製品が Defender for Cloud Apps と呼ばれていても、この名前を入力してください。

      add permission.

    • [委任されたアクセス許可]>[Investigation.Read]> の順に選んで、[アクセス許可の追加] を選択します

      application permissions.

    • 重要な注意事項: 関連するアクセス許可を選択します。 Investigation.Read は一例です。 その他のアクセス許可スコープについては、「サポートされているアクセス許可スコープ」を参照してください

      • 必要なアクセス許可を確認するには、呼び出す API の [アクセス許可] セクションを表示します。

    • [管理者の同意の付与] を選択します

      注: アクセス許可を追加するたびに、[管理者の同意の付与] を選択して新しいアクセス許可を有効にする必要があります。

      Image of Grant permissions.

  5. アプリケーション ID とテナント ID を書き留めます。

    • アプリケーション ページで、[概要] に移動し、次の情報をコピーします。

      Image of created app 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'' 要求を取得していることを検証します

  • 以下のスクリーンショットで、チュートリアルでアプリからデコードされたトークンが取得されていることを確認できます。

    Image of token validation.

トークンを使用して 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

関連項目