共用方式為

使用使用者內容存取 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 並驗證令牌。

注意事項

代表使用者存取 Microsoft Defender for Cloud Apps API 時，您需要正確的應用程式許可權和用戶權力。 如果您不熟悉 Microsoft Defender for Cloud Apps 的用戶權力，請參閱管理系統管理員存取權。

提示

如果您具有在入口網站中執行動作的許可權，您就有許可權可在 API 中執行動作。

建立應用程式

  1. 在 Microsoft Entra 系統管理中心 中，註冊新的應用程式。 如需詳細資訊，請參閱快速入門：向 Microsoft Entra 系統管理中心 註冊應用程式。

  2. 當 [ 註冊應用程式] 頁面出現時，輸入應用程式的註冊資訊：

    • 名稱 - 輸入對應用程式用戶顯示的有意義的應用程式名稱。

    • 支援的帳戶類型 - 選取您希望應用程式支援的帳戶。

      支援的帳戶類型 描述
      僅限此組織目錄中的帳戶 如果您要建置企業營運 (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。 例如， http://localhost:31544 可能是在本機電腦上執行之 Web 應用程式的 URL。 使用者會使用此 URL 來登入 Web 用戶端應用程式。
      • 針對公用用戶端應用程式，提供 Microsoft Entra ID 用來傳回令牌回應的 URI。 輸入應用程式特定的值，例如 myapp://auth。

      若要查看 Web 應用程式或原生應用程式的特定範例，請參閱我們的 快速入門。

      完成時，選取 [ 註冊]。

  3. 允許您的應用程式存取 Microsoft Defender for Cloud Apps 並指派「讀取警示」許可權：

    • 在您的應用程式頁面上，選取 [API 許可權>][新增>我的組織使用>類型Microsoft 雲端 App 安全性 的許可權 API]，然後選取 [Microsoft 雲端 App 安全性]。

    • 注意：Microsoft 雲端 App 安全性 不會出現在原始清單中。 開始在文字框中寫入其名稱，以查看其出現。 請務必輸入此名稱，即使產品現在稱為 Defender for Cloud Apps。

      新增許可權的螢幕快照。

    • 選擇 [委派的>許可權調查]。讀>取選取 [新增許可權]

      新增應用程式許可權的螢幕快照。

    • 重要注意事項：選取相關的許可權。 Investigation.Read 只是一個範例。 如需其他許可權範圍，請參閱 支援的許可權範圍

      • 若要判斷您需要的許可權，請在您想要呼叫的 API 中檢視 [許可權] 區段。

    • 選 取 [授與管理員同意]

      注意：每次新增許可權時，您都必須選取 [ 授與系統管理員同意 ]，新許可權才會生效。

      授與系統管理員許可權的螢幕快照。

  4. 記下您的應用程式識別碼和租使用者識別碼：

    • 在您的應用程式頁面上，移至 [ 概觀 ] 並複製下列資訊：

      已建立應用程式識別碼的螢幕快照。

支援的許可權範圍

許可權名稱 描述 支援的動作
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#

  • 在應用程式中複製/貼上下列類別。
  • 使用 AcquireUserTokenAsync 方法搭配您的應用程式識別碼、租使用者識別碼，以及驗證取得令牌。

注意事項

雖然下列程式代碼範例示範如何使用使用者名稱和密碼流程取得令牌，Microsoft建議您在生產環境中使用更安全的驗證流程。

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。

  • 在您傳送給 「Bearer {token}」 的 HTTP 要求中設定 Authorization 標頭， (持有人是授權配置)

  • 令牌的到期時間為 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

另請參閱