如何使用 Microsoft Entra ID 存取 Microsoft Graph 中的 Intune API

Microsoft 圖形 API 現在支援具有特定 API 和權限角色的 Microsoft Intune。 Microsoft 圖形 API 會使用 Microsoft Entra ID 進行驗證和存取控制。 存取 Microsoft Graph 中的 Intune API 需要：

• 具有以下內容的應用程式識別碼：

  • 呼叫 Microsoft Entra ID 和 Microsoft Graph API 的許可權。
  • 與特定應用程式工作相關的權限範圍。

• 具有以下功能的使用者認證：

  • 存取與應用程式相關聯的 Microsoft Entra 租用戶的許可權。
  • 支援應用程式權限範圍所需的角色權限。

• 使用者可授與應用程式許可權，以針對其 Azure 租用戶執行應用程式工作。

本文內容:

• 示範如何註冊應用程式以存取 Microsoft 圖形 API 和相關許可權角色。

• 描述 Intune API 許可權角色。

• 提供 C# 和 PowerShell 的 Intune API 驗證範例。

• 說明如何支援多個租用戶。

若要深入了解，請參閱：

• 使用 OAuth 2.0 和 Microsoft Entra ID 授權存取 Web 應用程式
• 開始使用 Microsoft Entra 驗證
• 將應用程式與 Microsoft Entra ID 整合
• 了解 OAuth 2.0

註冊應用程式以使用 Microsoft 圖形 API

若要註冊應用程式以使用 Microsoft 圖形 API：

1. 使用系統管理認證登入 Microsoft Entra 系統管理中心。

   視情況，您可以使用：

   • 租用戶管理員帳戶。
   • 已啟用 使用者可以註冊應用程式 設定的租用戶使用者帳戶。

2. 在系統管理中心中，展開 [身分識別>應用程式]，然後選取 [應用程式註冊]。

   

3. 選擇 [新增註冊 ] 以建立新應用程式，或選擇現有的應用程式。 (如果您選擇現有的應用程式，請略過下一個步驟 )

4. 在 [註冊應用程式] 窗格中，指定下列項目：

   • 當使用者登入) 時， (顯示應用程式的 名稱 。

   • 支援的帳戶類型。

   • 重新導向 URI 值。 此值為選用。

     注意事項

     Azure AD 圖形 API 正處於淘汰階段。 如需詳細資訊，請參閱更新您的應用程式以使用 MSAL) (驗證程式庫Microsoft Microsoft圖形 API。

     

     若要深入瞭解，請參閱 Microsoft Entra ID 的驗證案例。

5. 選取 [註冊] 以新增您的新應用程式。

   選取 [註冊]，即表示您同意 Microsoft 平台原則。

6. 從應用程式的應用程式窗格：

   1. 記下 應用程式 (用戶端) 識別碼 值。

   2. 然後，從導覽功能表中，選取 API 權限。

7. 從 API 許可權 窗格：

   1. 選取 [ 新增許可權]，然後在 [Microsoft API] 索引標籤上，選取 [Microsoft Graph ] 磚。

   2. 選取 [ 應用程式許可權 ] 選項以顯示所有可用的許可權，然後選取應用程式所需的許可權類型。

   3. 在相關名稱的左側勾選記號，以選擇應用程式所需的角色。 若要瞭解特定的 Intune 許可權範圍，請參閱 Intune 許可權範圍。 若要瞭解其他圖形 API 許可權範圍，請參閱 Microsoft Graph 許可權參考。

   為了獲得最佳結果，請選擇實作應用程式所需的最少角色。

資料倉儲和報告許可權

當您透過 Microsoft Entra 系統管理中心新增應用程式時，您可以根據應用程式的需求選擇 Intune API 許可權。

• get_data_warehouse - 使用此 API 許可權，從 Microsoft Intune 授與 Intune 數據倉儲 API 的存取權。 如需詳細資訊，請參閱 使用 Microsoft Intune Data Warehouse。

合作夥伴解決方案 API

透過 Microsoft Entra 系統管理中心新增應用程式時，可以使用下列 Intune API 許可權：

• get_device_compliance - 此 API 許可權可用來從 Microsoft Intune 取得裝置狀態和合規性資訊。 此 API 權限由網路存取控制合作夥伴使用。 如需詳細資訊，請參閱 網路存取控制與 Intune 整合。
• manage_partner_compliance_policy - 此 API 許可權可用來管理 Microsoft Intune 的合作夥伴合規性原則。 此 API 許可權可讓應用程式將合作夥伴合規性原則及其 Microsoft Entra 群組指派傳送至 Microsoft Intune，而不需要登入的使用者。 它由裝置合規性合作夥伴使用。 如需詳細資訊，請參閱 協力廠商裝置合規性合作夥伴。
• pfx_cert_provider - 此 API 許可權可用來將特定使用者的 PFX 憑證傳送至 Intune。 Intune 會將憑證傳遞至使用者註冊的所有裝置。 如需詳細資訊，請參閱 PFX 匯入 Powershell。
• scep_challenge_provider - 此 API 許可權可用來將 SCEP 挑戰傳送至 Intune，以進行憑證要求驗證。 它由憑證授權單位合作夥伴使用。 如需詳細資訊，請參閱合作夥伴 憑證授權單位。
• update_device_attributes - 此 API 許可權可用來從裝置合規性和行動威脅防禦合作夥伴將裝置資訊傳送至 Intune。 如需詳細資訊，請參閱 行動威脅防禦 與 Intune 和 協力廠商裝置合規性合作夥伴的整合。
• update_device_health - 此 API 許可權可用來從行動威脅防禦合作夥伴將裝置健康情況和威脅狀態資訊傳送至 Intune。 如需詳細資訊，請參閱 行動威脅防禦 與 Intune 整合。

如果您是有興趣使用這些 API 許可權與 Intune 整合的合作夥伴，請連絡 Microsoft 智慧型安全性協會] 小組以取得相關資訊。

完成後，選擇 Add permissions （新增許可 ） 以儲存變更。

此時，您還可以：

• 選擇授與所有租用戶帳戶使用應用程式的權限，而不提供認證。

  為此，您可以授予權限並接受確認提示。

  當您第一次執行應用程式時，系統會提示您授與應用程式執行所選角色的權限。

• 讓應用程式可供租使用者外部的使用者使用。 (這通常只有支援多個租用戶/組織的合作夥伴才需要 )

  若要這麼做︰

  1. 從應用程式窗格中選擇 Manifest （資訊清單 ）。

     

  2. 將設定的 availableToOtherTenants 值變更為 true。

  3. 儲存變更。

應用程式清單

如果您在使用 圖形 API 時要求應用程式清單時收到大量資料，可能會遇到 503 服務無法使用錯誤。 建議您使用較小的頁面大小（例如 20 個或更少的元素）重試。

Intune 許可權範圍

Microsoft Entra ID 和 Microsoft Graph 會使用許可權範圍來控制公司資源的存取。

許可權範圍也稱為 OAuth 範圍 () 控制特定 Intune 實體及其屬性的存取權。 本節摘要說明 Intune API 功能的許可權範圍。

若要深入了解：

• Microsoft Entra 驗證
• 應用程式權限範圍

當您將許可權授與 Microsoft Graph 時，您可以指定下列範圍來控制 Intune 功能的存取權：下表摘要說明 Intune API 許可權範圍。 第一欄顯示 Microsoft Intune 系統管理中心 中顯示的功能名稱，而第二欄則提供許可權範圍名稱。

下表會列出 Microsoft Intune 系統管理中心中顯示的設定。 下列各節會依字母順序說明範圍。

目前，所有 Intune 許可權範圍都需要系統管理員存取權。 這表示您在執行存取 Intune API 資源的應用程式或腳本時，需要對應的認證。

DeviceManagementApps.Read.All

• 啟用存取 設定： 讀取 Microsoft Intune 應用程式

• 允許讀取下列實體屬性和狀態的存取權：

  • 用戶端應用程式
  • 行動應用程式類別
  • 應用程式保護原則
  • 應用程式設定

DeviceManagementApps.ReadWrite.All

• 啟用存取 設定： 讀取和寫入 Microsoft Intune 應用程式

• 允許與 DeviceManagementApps.Read.All 相同的作業

• 也允許變更下列實體：

  • 用戶端應用程式
  • 行動應用程式類別
  • 應用程式保護原則
  • 應用程式設定

DeviceManagementConfiguration.Read.全部

• 啟用存取 設定： 讀取 Microsoft Intune 裝置設定和原則

• 允許讀取下列實體屬性和狀態的存取權：

  • 裝置設定
  • 裝置合規性原則
  • 通知訊息

DeviceManagementConfiguration.ReadWrite.All

• 啟用存取 設定： 讀取和寫入 Microsoft Intune 裝置設定和原則

• 允許與 DeviceManagementConfiguration.Read.All 相同的作業

• 應用程式也可以建立、指派、刪除和變更下列實體：

  • 裝置設定
  • 裝置合規性原則
  • 通知訊息

DeviceManagementManagedDevices.PrivilegedOperations.All

• 啟用存取 設定： 在 Microsoft Intune 裝置上執行影響使用者的遠端動作

• 允許在受管理裝置上執行下列遠端動作：

  • 淘汰
  • 擦去
  • 重設/恢復密碼
  • 遠端鎖定
  • 啟用/禁用丟失模式
  • 乾淨的電腦
  • 重新開機
  • 從共用裝置刪除使用者

DeviceManagementManagedDevices.Read.All

• 啟用存取 設定： 讀取 Microsoft Intune 裝置

• 允許讀取下列實體屬性和狀態的存取權：

  • 受管理裝置
  • 設備類別
  • 偵測到的應用程式
  • 遠端動作
  • 惡意軟體資訊

DeviceManagementManagedDevices.ReadWrite.All

• 啟用存取 設定： 讀取和寫入 Microsoft Intune 裝置

• 允許與 DeviceManagementManagedDevices.Read.All 相同的作業

• 應用程式也可以建立、刪除和變更下列實體：

  • 受管理裝置
  • 設備類別

• 也允許下列遠端動作：

  • 尋找裝置
  • 停用啟用鎖定
  • 請求遠端協助

DeviceManagementRBAC.讀取.全部

• 啟用存取 設定： 讀取 Microsoft Intune RBAC 設定

• 允許讀取下列實體屬性和狀態的存取權：

  • 角色指派
  • 角色定義
  • 資源作業

DeviceManagementRBAC.ReadWrite.All

• 啟用存取 設定： 讀取和寫入 Microsoft Intune RBAC 設定

• 允許與 DeviceManagementRBAC.Read.All 相同的作業

• 應用程式也可以建立、指派、刪除和變更下列實體：

  • 角色指派
  • 角色定義

DeviceManagementScripts.Read.全部

• 啟用存取 設定： 讀取 Microsoft Intune 腳本

• 應用程式可以檢視 (讀取) 指令碼，具體來說：

  • 裝置殼層指令碼
  • 裝置健康情況指令碼
  • 裝置合規性指令碼
  • 裝置自訂屬性 Shell 指令碼
  • 裝置管理指令碼

DeviceManagementScripts.ReadWrite.All

• 啟用存取 設定： 讀取和寫入 Microsoft Intune 腳本
  允許與 DeviceManagementScripts.Read.All 相同的作業

• 應用程式可以建立、更新或刪除指令碼，具體來說：

  • 裝置殼層指令碼
  • 裝置健康情況指令碼
  • 裝置合規性指令碼
  • 裝置自訂屬性 Shell 指令碼
  • 裝置管理指令碼

DeviceManagementServiceConfig.Read.All

• 啟用存取 設定： 讀取 Microsoft Intune 設定

• 允許讀取下列實體屬性和狀態的存取權：

  • 裝置註冊
  • Apple 推播通知憑證
  • Apple 裝置註冊計劃
  • Apple 批量購買計劃
  • Exchange 連接器
  • 條款及細則
  • 雲端 PKI
  • 品牌
  • 行動威脅防禦應用程式

DeviceManagementServiceConfig.ReadWrite.All

• 啟用存取 設定： 讀取和寫入 Microsoft Intune 設定

• 允許與DeviceManagementServiceConfig.Read.All_相同的操作

• 應用程式也可以設定下列 Intune 功能：

  • 裝置註冊
  • Apple 推播通知憑證
  • Apple 裝置註冊計劃
  • Apple 批量購買計劃
  • Exchange 連接器
  • 條款及細則
  • 雲端 PKI
  • 品牌
  • 行動威脅防禦應用程式

Microsoft Entra 驗證範例

本節說明如何將 Microsoft Entra ID 併入 C# 和 PowerShell 專案。

在每個範例中，您必須指定應用程式識別碼，該識別碼至少 DeviceManagementManagedDevices.Read.All 具有先前) 所討論 (權限範圍。

測試任一範例時，您可能會收到 HTTP 狀態 403 (禁止) 錯誤，類似下列內容：

{
  "error": {
    "code": "Forbidden",
    "message": "Application is not authorized to perform this operation - Operation ID " +
       "(for customer support): 00000000-0000-0000-0000-000000000000 - " +
       "Activity ID: cc7fa3b3-bb25-420b-bfb2-1498e598ba43 - " +
       "Url: https://example.manage.microsoft.com/" +
       "Service/Resource/RESTendpoint?" +
       "api-version=2017-03-06 - CustomApiErrorPhrase: ",
    "innerError": {
      "request-id": "00000000-0000-0000-0000-000000000000",
      "date": "1980-01-0112:00:00"
    }
  }
}

如果發生這種情況，請確認：

• 您已將應用程式識別碼更新為授權使用 Microsoft 圖形 API 和DeviceManagementManagedDevices.Read.All權限範圍的應用程式識別碼。

• 您的租用戶認證支援系統管理功能。

• 您的程式碼類似於顯示的範例。

在 C 中驗證 Microsoft Entra ID#

此範例示範如何使用 C# 來擷取與 Intune 帳戶相關聯的裝置清單。

1. 啟動 Visual Studio，然後建立新的 Visual C# 主控台應用程式 (.NET Framework) 專案。

2. 輸入專案的名稱，並視需要提供其他詳細資料。

   

3. 使用方案總管將 Microsoft MSAL NuGet 套件新增至專案：

   1. 以滑鼠右鍵按一下 [方案總管]。
   2. 選擇 [管理 NuGet 套件...]>瀏覽。
   3. 選取Microsoft.Identity.Client，然後選擇 [安裝]。

4. 將下列陳述式新增至 Program.cs頂端：

   using Microsoft.Identity.Client;
   using System.Net.Http;
   

5. 新增建立授權標頭的方法：

   private static async Task<string> GetAuthorizationHeader()
   {
       string applicationId = "<Your Application ID>";
       string authority = "https://login.microsoftonline.com/common/";
       Uri redirectUri = new Uri("urn:ietf:wg:oauth:2.0:oob");
       AuthenticationContext context = new AuthenticationContext(authority);
       AuthenticationResult result = await context.AcquireTokenAsync(
           "https://graph.microsoft.com",
           applicationId, redirectUri,
           new PlatformParameters(PromptBehavior.Auto));
       return result.CreateAuthorizationHeader();
   

   請記得變更 的 application_ID 值，以符合至少 DeviceManagementManagedDevices.Read.All 授予權限範圍的值，如前所述。

6. 新增擷取裝置清單的方法：

   private static async Task<string> GetMyManagedDevices()
   {
       string authHeader = await GetAuthorizationHeader();
       HttpClient graphClient = new HttpClient();
       graphClient.DefaultRequestHeaders.Add("Authorization", authHeader);
       return await graphClient.GetStringAsync(
           "https://graph.microsoft.com/beta/me/managedDevices");
   }
   

7. 更新 Main 以呼叫 GetMyManagedDevices：

   string devices = GetMyManagedDevices().GetAwaiter().GetResult();
   Console.WriteLine(devices);
   

8. 編譯並運行您的程序。

當您第一次執行程式時，您應該會收到兩個提示。 第一個會要求您的認證，第二個會授與請求的 managedDevices 許可。

作為參考，以下是已完成的程序：

using Microsoft.Identity.Client;
using System;
using System.Net.Http;
using System.Threading.Tasks;

namespace IntuneGraphExample
{
    class Program
    {
        static void Main(string[] args)
        {
            string devices = GetMyManagedDevices().GetAwaiter().GetResult();
            Console.WriteLine(devices);
        }

        private static async Task<string> GetAuthorizationHeader()
        {
            string applicationId = "<Your Application ID>";
            string authority = "https://login.microsoftonline.com/common/";
            Uri redirectUri = new Uri("urn:ietf:wg:oauth:2.0:oob");
            AuthenticationContext context = new AuthenticationContext(authority);
            AuthenticationResult result = await context.AcquireTokenAsync("https://graph.microsoft.com", applicationId, redirectUri, new PlatformParameters(PromptBehavior.Auto));
            return result.CreateAuthorizationHeader();
        }

        private static async Task<string> GetMyManagedDevices()
        {
            string authHeader = await GetAuthorizationHeader();
            HttpClient graphClient = new HttpClient();
            graphClient.DefaultRequestHeaders.Add("Authorization", authHeader);
            return await graphClient.GetStringAsync("https://graph.microsoft.com/beta/me/managedDevices");
        }
    }
}

使用 Microsoft Graph PowerShell 驗證 Microsoft Entra ID

PowerShell 腳本可以使用 Microsoft Graph PowerShell 模組進行驗證。 若要深入瞭解，請參閱 Microsoft Graph PowerShell 和 Intune PowerShell 範例。

支援多個租戶和合作夥伴

如果您的組織支援具有自己的 Microsoft Entra 租用戶的組織，您可能想要允許用戶端搭配其各自的租用戶使用您的應用程式。

若要這麼做︰

1. 確認用戶端帳戶存在於目標 Microsoft Entra 租使用者中。

2. 確認您的租用戶帳戶允許使用者註冊應用程式， (請參閱 使用者設定) 。

3. 在每個租戶之間建立關係。

   若要這樣做，請執行下列其中一項操作：

   a. 使用 Microsoft 合作夥伴中心 來定義與用戶端及其電子郵件地址的關聯性。

   b. 邀請使用者成為租用戶的來賓。

若要邀請使用者成為租使用者的來賓：

1. 從 [快速任務] 面板中選擇 [新增來賓使用者]。

   

2. 輸入客戶的電子郵件地址，並 (選擇性地) 為邀請添加個性化消息。

   

3. 選擇 Invite （邀請）。

這會向使用者傳送邀請。

使用者需要選擇 [開始使用 ] 連結才能接受您的邀請。

建立關係 (或您的邀請已) 接受時，請將使用者帳戶新增至 目錄角色。

請記得視需要將使用者新增至其他角色。 例如，若要允許使用者管理 Intune 設定，他們必須至少是 Intune 服務系統管理員。

亦：

• 用 https://admin.microsoft.com 來將 Intune 授權指派給您的使用者帳戶。

• 更新應用程式程式碼，以驗證用戶端的 Microsoft Entra 租用戶網域，而不是您自己的網域。

  例如，假設您的租用戶網域是， contosopartner.onmicrosoft.com 而用戶端的租用戶網域是 northwind.onmicrosoft.com，您會更新程式碼，以向用戶端的租用戶進行驗證。

  若要在以先前範例為基礎的 C# 應用程式中執行此動作，您必須變更變數的 authority 值：

  string authority = "https://login.microsoftonline.com/common/";
  

  這一行變更為

  string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";