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

發行項
11/19/2024

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 驗證範例。
描述如何支援多個租使用者。

若要深入了解，請參閱：

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

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

使用系統管理認證登入 Microsoft Intune 系統管理中心。

視需要，您可以使用：
- 租用戶系統管理員帳戶。
- 已啟用 [ 用戶可以註冊應用程式 ] 設定的租用戶用戶帳戶。
選取 [所有服務>M365 Microsoft Entra ID>Microsoft Entra ID>應用程式註冊。
選擇 [新增註冊 ] 以建立新的應用程式，或選擇現有的應用程式。 (如果您選擇現有的應用程式，請略過下一個步驟。)
在 [ 註冊應用程式] 窗格中，指定下列專案：
- 當使用者登入) 時， (顯示的應用程式名稱。
- 支援的帳戶類型。
- 重新導向 URI 值。 此值為選項。
  
  注意事項
  
  Azure AD 圖形 API 處於淘汰階段。如需詳細資訊，請參閱更新您的應用程式以使用Microsoft驗證連結庫 (MSAL) 和Microsoft 圖形 API。
  
  若要深入瞭解，請參閱 Microsoft Entra ID的驗證案例。
從應用程式窗格：
1. 請記下應用程式 (用戶端) 識別 碼值。
2. 選取 [API 許可權]。
從 [API 許可權] 窗格中，選擇 [Microsoft Graph 新增>許可權Microsoft API>]。然後，選取應用程式所需的許可權類型。

將複選標記放在相關名稱的左邊，以選擇應用程式所需的角色。若要瞭解特定 Intune 許可權範圍，請參閱 Intune 許可權範圍。若要瞭解其他圖形 API 許可權範圍，請參閱Microsoft圖形許可權參考。

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

數據倉儲和報告許可權

當您透過 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。如需詳細資訊，請參閱Mobile Threat Defense 與 Intune和第三方裝置合規性合作夥伴的整合。
update_device_health - 此 API 許可權可用來將裝置健康情況和威脅狀態資訊傳送至行動裝置威脅防禦合作夥伴 Intune。如需詳細資訊，請參閱Mobile Threat Defense 與 Intune整合。

如果您是想要使用這些 API 許可權與 Intune 整合的合作夥伴，請連絡 Microsoft Intelligent Security Association] 小組以取得資訊。

完成後，選擇 [新增許可權 ] 以儲存變更。

此時，您也可以：

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

若要這樣做，您可以授與許可權並接受確認提示。

當您第一次執行應用程式時，系統會提示您授與應用程式執行所選角色的許可權。
將應用程式提供給租使用者外部的使用者使用。 (這通常僅適用於支援多個租使用者/組織.)

若要這麼做︰
1. 從應用程式窗格中選擇 [指令清單]。
2. 將設定的 availableToOtherTenants 值變更為 true。
3. 儲存變更。

應用程式清單

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

Intune許可權範圍

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

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

若要深入了解：

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

啟用存取設定	範圍名稱
在 Microsoft Intune 裝置上執行影響使用者的遠端動作	DeviceManagementManagedDevices.PrivilegedOperations.All
讀取和寫入 Microsoft Intune 裝置	DeviceManagementManagedDevices.ReadWrite.All
讀取 Microsoft Intune 裝置	DeviceManagementManagedDevices.Read.All
讀取和寫入 Microsoft Intune RBAC 設定	DeviceManagementRBAC.ReadWrite.All
讀 Microsoft Intune RBAC 設定	DeviceManagementRBAC.Read.All
讀取和寫入 Microsoft Intune 應用程式	DeviceManagementApps.ReadWrite.All
讀取 Microsoft Intune 應用程式	DeviceManagementApps.Read.All
讀取和寫入 Microsoft Intune 裝置設定和原則	DeviceManagementConfiguration.ReadWrite.All
讀 Microsoft Intune 裝置設定和原則	DeviceManagementConfiguration.Read.All
讀取和寫入 Microsoft Intune 組態	DeviceManagementServiceConfig.ReadWrite.All
讀取 Microsoft Intune 組態	DeviceManagementServiceConfig.Read.All

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

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

DeviceManagementApps.Read.All

啟用存取設定：讀取 Microsoft Intune 應用程式
允許下列實體屬性和狀態的讀取權限：
- 用戶端應用程式
- 行動應用程式類別
- 應用程式保護原則
- 應用程式組態

DeviceManagementApps.ReadWrite.All

啟用存取設定：讀取和寫入 Microsoft Intune 應用程式
允許與 DeviceManagementApps.Read.All 相同的作業
也允許對下列實體進行變更：
- 用戶端應用程式
- 行動應用程式類別
- 應用程式保護原則
- 應用程式組態

DeviceManagementConfiguration.Read.All

啟用存取設定：讀取 Microsoft Intune 裝置設定和原則
允許下列實體屬性和狀態的讀取權限：
- 裝置設定
- 裝置合規性政策
- 通知訊息

DeviceManagementConfiguration.ReadWrite.All

啟用存取設定：Microsoft Intune 裝置設定和原則讀取和寫入
允許與 DeviceManagementConfiguration.Read.All 相同的作業
應用程式也可以建立、指派、刪除和變更下列實體：
- 裝置設定
- 裝置合規性政策
- 通知訊息

DeviceManagementManagedDevices.PrivilegedOperations.All

啟用存取設定：在 Microsoft Intune 裝置上執行影響使用者的遠端動作
允許在受控裝置上執行下列遠端動作：
- 淘汰
- 擦去
- 重設/復原密碼
- 遠端鎖定
- 啟用/停用遺失模式
- 清除電腦
- 重新開機
- 從共用裝置刪除使用者

DeviceManagementManagedDevices.Read.All

啟用存取設定：讀取 Microsoft Intune 裝置
允許下列實體屬性和狀態的讀取權限：
- Managed 裝置
- 裝置類別
- 偵測到的應用程式
- 遠端動作
- 惡意代碼資訊

DeviceManagementManagedDevices.ReadWrite.All

啟用存取設定：Microsoft Intune 裝置讀取和寫入
允許與 DeviceManagementManagedDevices.Read.All 相同的作業
應用程式也可以建立、刪除和變更下列實體：
- Managed 裝置
- 裝置類別
也允許下列遠端動作：
- 找出裝置
- 停用啟用鎖定
- 要求遠端協助

DeviceManagementRBAC.Read.All

啟用存取設定：讀取 Microsoft Intune RBAC 設定
允許下列實體屬性和狀態的讀取權限：
- 角色指派
- 角色定義
- 資源作業

DeviceManagementRBAC.ReadWrite.All

啟用存取設定：讀取和寫入 Microsoft Intune RBAC 設定
允許與 DeviceManagementRBAC.Read.All 相同的作業
應用程式也可以建立、指派、刪除和變更下列實體：
- 角色指派
- 角色定義

DeviceManagementServiceConfig.Read.All

啟用存取設定：讀取 Microsoft Intune 組態
允許下列實體屬性和狀態的讀取權限：
- 裝置註冊
- Apple 推播通知憑證
- Apple 裝置註冊計劃
- Apple 大量採購方案
- Exchange Connector
- 條款及條件
- 雲端 PKI
- 品牌
- 行動威脅防禦應用程式

DeviceManagementServiceConfig.ReadWrite.All

啟用存取設定：讀取和寫入 Microsoft Intune 組態
允許與DeviceManagementServiceConfig.Read.All_相同的作業
應用程式也可以設定下列 Intune 功能：
- 裝置註冊
- Apple 推播通知憑證
- Apple 裝置註冊計劃
- Apple 大量採購方案
- Exchange Connector
- 條款及條件
- 雲端 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 帳戶相關聯的裝置清單。

注意事項

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

啟動 Visual Studio，然後建立新的 Visual C# 控制台應用程式 (.NET Framework) 專案。
輸入項目的名稱，並視需要提供其他詳細數據。
使用方案總管將 msAL NuGet Microsoft套件新增至專案：
1. 以滑鼠右鍵按兩下方案總管。
2. 選擇 [管理 NuGet 套件...>]流覽。
3. 選取 Microsoft.Identity.Client ，然後選擇 [ 安裝]。

將下列語句新增至 Program.cs的頂端：

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

新增方法以建立授權標頭：

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 授與許可權範圍的值，如先前所述。

新增方法以擷取裝置清單：

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");
}

更新 Main 以呼叫 GetMyManagedDevices：

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

編譯並執行您的程式。

當您第一次執行程式時，應該會收到兩個提示。第一個要求您的認證，第二個會授與要求的 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 租使用者的組織，您可能會想要允許用戶端將您的應用程式與各自的租使用者搭配使用。

若要這麼做︰

確認客戶端帳戶存在於目標 Microsoft Entra 租使用者中。
確認您的租用戶帳戶允許用戶註冊應用程式 (請參閱 用戶設定) 。
建立每個租用戶之間的關聯性。

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

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

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

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

從 [快速工作] 面板中選擇 [新增來賓使用者]。
輸入客戶端的電子郵件地址， (選擇性地) 為邀請新增個人化訊息。
選擇 [邀請]。

這會傳送邀請給使用者。

用戶必須選擇 [ 開始使用] 連結，才能接受您的邀請。

建立關聯性 (或您的邀請已) 接受時，請將用戶帳戶新增至 Directory 角色。

請記得視需要將使用者新增至其他角色。例如，若要允許使用者管理 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/";
```

共用方式為