如何使用Microsoft Entra ID访问 Microsoft Graph 中的 Intune API

Microsoft 图形 API现在支持具有特定 API 和权限角色的Microsoft Intune。 Microsoft 图形 API使用 Microsoft Entra ID 进行身份验证和访问控制。
在 Microsoft Graph 中访问 Intune API 需要:

  • 应用程序 ID 需要具有:

    • 调用Microsoft Entra ID和 Microsoft Graph API 的权限。
    • 与具体应用程序任务相关的权限范围。
  • 用户凭据需要具有:

    • 访问与应用程序关联的Microsoft Entra租户的权限。
    • 支持应用程序权限范围所需的角色权限。
  • 向应用授予为其 Azure 租户执行应用程序任务的权限的最终用户。

本文:

  • 演示如何将应用程序注册为对 Microsoft 图形 API和相关权限角色的访问权限。

  • 介绍 Intune API 权限角色。

  • 提供适用于 C# 和 PowerShell 的 Intune API 身份验证示例。

  • 介绍如何支持多个租户。

若要了解详细信息,请参阅:

注册应用以使用 Microsoft Graph API

注册应用以使用 Microsoft Graph API:

  1. 使用管理凭据登录到 Microsoft Intune 管理中心

    根据需要可以使用:

    • 租户管理员帐户。
    • 启用了“ 用户可以注册应用程序 ”设置的租户用户帐户。
  2. 选择“所有服务>M365 Microsoft Entra ID>Microsoft Entra ID>应用注册”。

    应用注册菜单命令
  3. 选择“新建注册”,以创建新的应用程序,或选择现有应用程序。 (如果选择现有应用程序,请跳过下一步。)

  4. 在“ 注册应用程序 ”窗格中,指定以下内容:

  5. 在应用程序窗格中:

    1. 请注意 应用程序 (客户端) ID 值。

    2. 选择API 权限

  6. “API 权限 ”窗格中,选择 “添加权限>”“Microsoft API>Microsoft Graph”。 然后,选择应用程序所需的权限类型。

    通过在相关名称的左侧添加复选标记,选择应用所需的角色。 若要了解特定的 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 Intune发送合作伙伴合规性策略及其Microsoft Entra组分配。 它由设备合规性合作伙伴使用。 有关详细信息,请参阅 第三方设备合规性合作伙伴
  • 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 智能安全关联] 团队了解相关信息。

完成后,选择 “添加权限” 以保存更改。

此时,还可以:

  • 选择授予所有租户帐户使用应用的权限,而无需提供凭据。

    为此,可选择“授予权限”并接受确认提示。

    首次运行应用程序时,系统会提示你授予应用执行所选角色的权限。

  • 使应用可供租户外部的用户使用。 (通常只有支持多个租户/组织的合作伙伴才需要此功能。)

    为此,请执行以下操作:

    1. 从应用程序窗格中选择“ 清单 ”。

      “编辑清单”边栏选项卡
    2. 将 设置的值 availableToOtherTenants 更改为 true

    3. 保存所做的更改。

应用列表

如果在使用 图形 API 时请求应用列表时收到大量数据,可能会遇到 503 服务不可用错误。 建议使用较小的页面大小(例如 20 个或更少的元素)重试。

Intune 权限范围

Microsoft Entra ID和 Microsoft Graph 使用权限范围来控制对公司资源的访问。

权限范围 (也称为 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 权限范围都需要管理员访问权限。 这意味着,在运行访问 Intune API 资源的应用或脚本时,需要相应的凭据。

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设备

  • 允许对以下实体属性和状态进行读取访问:

    • 托管设备
    • 设备类别
    • 检测到的应用
    • 远程操作
    • 恶意软件信息

DeviceManagementManagedDevices.ReadWrite.All

  • 启用访问设置:读取和写入Microsoft Intune设备

  • 允许与 DeviceManagementManagedDevices.Read.All 相同的操作

  • 应用还可以创建、删除和更改以下实体:

    • 托管设备
    • 设备类别
  • 还允许以下远程操作:

    • 查找设备
    • 禁用激活锁定
    • 请求远程协助

DeviceManagementRBAC.Read.All

  • 启用访问设置:读取Microsoft Intune RBAC 设置

  • 允许对以下实体属性和状态进行读取访问:

    • 角色分配
    • 角色定义
    • 资源操作

DeviceManagementRBAC.ReadWrite.All

  • 启用访问设置:读取和写入Microsoft Intune RBAC 设置

  • 允许与 DeviceManagementRBAC.Read.All 相同的操作

  • 应用还可以创建、分配、删除和更改以下实体:

    • 角色分配
    • 角色定义

DeviceManagementServiceConfig.Read.All

  • 启用访问设置:读取Microsoft Intune配置

  • 允许对以下实体属性和状态进行读取访问:

    • 设备注册
    • Apple 推送通知证书
    • Apple 设备注册计划
    • Apple Volume Purchase Program
    • Exchange 连接器
    • 条款和条件
    • 云 PKI
    • 品牌打造
    • 移动威胁防御

DeviceManagementServiceConfig.ReadWrite.All

  • 启用访问设置:读取和写入Microsoft Intune配置

  • 允许与 DeviceManagementServiceConfig.Read.All_ 相同的操作

  • 应用还可以配置以下 Intune 功能:

    • 设备注册
    • Apple 推送通知证书
    • Apple 设备注册计划
    • Apple Volume Purchase Program
    • Exchange 连接器
    • 条款和条件
    • 云 PKI
    • 品牌打造
    • 移动威胁防御

Microsoft Entra身份验证示例

本部分介绍如何将Microsoft Entra ID合并到 C# 和 PowerShell 项目中。

在每个示例中,都需要指定至少 DeviceManagementManagedDevices.Read.All 具有) 前面讨论 (权限范围的应用程序 ID。

测试任一示例时,可能会收到 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"
    }
  }
}

如果发生这种情况,请验证:

  • 你已将应用程序 ID 更新为有权使用 Microsoft 图形 API和DeviceManagementManagedDevices.Read.All权限范围的 ID。

  • 租户凭据支持管理功能。

  • 代码类似于显示的示例。

在 C 中对Microsoft Entra ID进行身份验证#

此示例演示如何使用 C# 检索与 Intune 帐户关联的设备列表。

注意

Azure AD 图形 API处于停用阶段。 有关详细信息,请参阅 更新应用程序以使用 Microsoft 身份验证库 (MSAL) 和 Microsoft Graph API

  1. 启动 Visual Studio,然后 (.NET Framework) 项目创建新的 Visual C# 控制台应用。

  2. 输入项目的名称,并根据需要提供其他详细信息。

    在 Visual Studio 中创建 C# 控制台应用项目
  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 PowerShellIntune PowerShell 示例

支持多个租户和合作伙伴

如果你的组织支持具有其自己的Microsoft Entra租户的组织,你可能希望允许客户端将应用程序用于其各自的租户。

为此,请执行以下操作:

  1. 验证目标Microsoft Entra租户中是否存在客户端帐户。

  2. 验证租户帐户是否允许用户注册应用程序 (请参阅用户 设置) 。

  3. 在每个租户之间建立关系。

    为此,请执行以下任一操作:

    a. 使用 Microsoft 合作伙伴中心 定义与你的客户及其电子邮件地址的关系。

    b. 邀请用户成为租户的来宾。

若要邀请用户成为租户的来宾,请执行以下操作:

  1. “快速任务”面板中选择“添加来宾用户”。

    使用快速任务添加来宾用户
  2. 输入客户端的电子邮件地址, ((可选)) 为邀请添加个性化消息。

    邀请外部用户作为来宾
  3. 选择 “邀请”。

这会向用户发送邀请。

示例来宾邀请

用户需要选择 “入门” 链接才能接受邀请。

建立关系 (或已接受邀请) 时,将用户帐户添加到 “目录”角色

请记住根据需要将用户添加到其他角色。 例如,若要允许用户管理 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/";