Как использовать Microsoft Entra ID для доступа к API Intune в Microsoft Graph

Microsoft API Graph теперь поддерживает Microsoft Intune с определенными API-интерфейсами и ролями разрешений. Microsoft API Graph использует Microsoft Entra ID для проверки подлинности и управления доступом. Для доступа к API Intune в Microsoft Graph требуется:

• Идентификатор приложения со следующими характеристиками:

  • Разрешение на вызов Microsoft Entra ID и API Microsoft Graph.
  • Области разрешений, соответствующие задачам конкретного приложения.

• Учетные данные пользователя со следующими характеристиками:

  • Разрешение на доступ к клиенту Microsoft Entra, связанному с приложением.
  • Разрешения ролей, необходимые для поддержки областей разрешений приложения.

• Конечный пользователь должен предоставить приложению разрешение на выполнение задач приложения для своего клиента Azure.

В этой статье:

• Регистрация приложения с доступом к Microsoft API Graph и соответствующими ролями разрешений.

• Описывает роли разрешений API Intune.

• Предоставляет примеры проверки подлинности API Intune для C# и PowerShell.

• Описывается поддержка нескольких клиентов.

Дополнительные сведения см. в статьях

• Авторизация доступа к веб-приложениям с помощью OAuth 2.0 и Microsoft Entra ID
• Начало работы с проверкой подлинности Microsoft Entra
• Интеграция приложений с Microsoft Entra ID
• Общие сведения об OAuth 2.0

Регистрация приложений для использования API Microsoft Graph

Чтобы зарегистрировать приложение для использования API Microsoft Graph, выполните следующие действия:

1. Войдите в Центр администрирования Microsoft Entra, используя учетные данные администратора.

   При необходимости можно использовать следующие учетные записи:

   • Учетная запись администратора клиента.
   • Учетная запись пользователя клиента с включенным параметром "Пользователи могут регистрировать приложения ".

2. В Центре администрирования разверните Приложения удостоверений> и выберите пункт "Регистрация приложений".

   

3. Щелкните Новая регистрация, чтобы создать новое приложение, или выберите существующее приложение. (Если вы выбрали существующее приложение, пропустите следующий шаг.)

4. В области "Регистрация приложения " укажите следующее:

   • Имя приложения (отображается при входе пользователей).

   • Поддерживаемый тип учетной записи.

   • Значение URI перенаправления . Это значение является необязательным.

     Примечание.

     Azure AD API Graph находится на этапе прекращения поддержки. Подробности см. в статье Обновление приложений, чтобы использовать библиотеку проверки подлинности Майкрософт (MSAL) и API Microsoft Graph

     

     Чтобы узнать больше, см. Сценарии проверки подлинности для Microsoft Entra ID.

5. Выберите "Зарегистрироваться", чтобы добавить новое приложение.

   Выбирая «Зарегистрироваться», вы соглашаетесь с политиками платформы Microsoft.

6. В области приложения для вашего приложения:

   1. Запомните значение Идентификатор приложения (клиента).

   2. Затем в меню навигации выберите "Разрешения API".

7. Из панели разрешений API :

   1. Выберите "Добавить разрешение", а затем на вкладке Microsoft API выберите плитку Microsoft Graph .

   2. Выберите параметр "Разрешения приложения", чтобы отобразить все доступные разрешения, а затем выберите тип разрешений, необходимых вашему приложению.

   3. Выберите роли, необходимые для вашего приложения, установив флажок слева от соответствующих имен. Сведения о конкретных областях разрешений Intune см. в разделе Области разрешений Intune. Сведения о других областях разрешений API Graph см. в справочнике по разрешениям Microsoft Graph.

   Рекомендуется выбирать наименьшее количество ролей, необходимых для реализации приложения.

Разрешения на хранилище данных и создание отчетов

При добавлении приложения через Центр администрирования Microsoft Entra вы можете выбрать разрешения API Intune в зависимости от требований приложения.

• get_data_warehouse — используйте это разрешение API для предоставления доступа к API хранилища данных Intune из Microsoft Intune. Дополнительные сведения см. в разделе Использование Microsoft Intune Data Warehouse.

API партнерских решений

При добавлении приложения через Центр администрирования Microsoft Entra доступны следующие разрешения API Intune:

• 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 Import Powershell.
• scep_challenge_provider — это разрешение API используется для отправки вызовов SCEP в Intune для проверки запроса сертификата. Используется партнерами центров сертификации. Дополнительные сведения см. в разделе Партнерский центр сертификации.
• update_device_attributes — это разрешение API используется для отправки сведений об устройстве в Intune от партнеров по соответствию устройств требованиям и защите от мобильных угроз. Дополнительные сведения см. в статье "Интеграция защиты от угроз в мобильных устройствах" с Intune и сторонними партнерами, соблюдающими нормативные требования.
• update_device_health — это разрешение API используется для отправки сведений о работоспособности устройства и состоянии угрозы в Intune от партнеров по защите от мобильных устройств. Подробнее об интеграции Защиты от угроз в мобильных устройствах с Intune.

Если вы являетесь партнером, заинтересованным в интеграции с Intune с использованием этих разрешений API, обратитесь за справкой в группу Microsoft Intelligent Security Association.

По завершении выберите "Добавить разрешения", чтобы сохранить изменения.

На этом этапе вы также можете:

• Выберите, чтобы предоставить разрешение всем учетным записям клиента на использование приложения без предоставления учетных данных.

  Для этого можно предоставить разрешения и подтвердить действия в появившемся окне запроса.

  При первом запуске приложения вам будет предложено предоставить приложению разрешение на выполнение выбранных ролей.

• Сделайте приложение доступным для пользователей за пределами клиента. (Обычно это требуется только для партнеров, поддерживающих несколько клиентов или организаций.)

  Для этого:

  1. Выберите "Манифест" в области приложения.

  2. Измените значение параметра availableToOtherTenants на true.

  3. Сохраните изменения.

Описание приложения

Если вы получаете большой объем данных при запросе списка приложения при использовании API Graph, вы можете столкнуться с ошибкой 503 "Служба недоступна". Рекомендуем повторить попытку с меньшим размером страницы, например 20 или менее элементов.

Области разрешений Intune

Microsoft Entra ID и Microsoft Graph используют области разрешений для управления доступом к корпоративным ресурсам.

Области разрешений (также называемые областями OAuth) управляют доступом к определенным объектам Intune и их свойствам. В этом разделе обобщены области разрешений для функций API Intune.

Дополнительные сведения:

• Проверка подлинности Microsoft Entra
• Области разрешений для приложений

При предоставлении разрешения Microsoft Graph можно указать следующие области для управления доступом к функциям Intune: В следующей таблице обобщены области разрешений API Intune. В первом столбце указано имя функции, отображаемое в Центре администрирования Microsoft Intune, а во втором — область имя разрешения.

В таблице перечислены параметры в том виде, в котором они отображаются в Центре администрирования Microsoft Intune. В следующих разделах области описаны в алфавитном порядке.

В настоящее время для всех областей разрешений Intune требуется доступ администратора. Это означает, что вам требуются соответствующие учетные данные при запуске приложений или сценариев, которые обращаются к ресурсам API Intune.

DeviceManagementApps.Read.All

• Параметр "Включить Access": чтение приложений Microsoft Intune

• Предоставляет доступ на чтение к следующим свойствам и состоянию объекта:

  • Клиентские приложения
  • Категории мобильных приложений
  • Политики защиты приложений
  • Конфигурации приложений

DeviceManagementApps.ReadWrite.All

• Параметр "Включить Access": чтение и запись приложений Microsoft Intune

• Разрешает те же операции, что и DeviceManagementApps.Read.All

• Также разрешает изменения в следующих сущностях:

  • Клиентские приложения
  • Категории мобильных приложений
  • Политики защиты приложений
  • Конфигурации приложений

DeviceManagementConfiguration.Read.All

• Параметр "Включить доступ": ознакомьтесь с конфигурацией и политиками устройства Microsoft Intune

• Предоставляет доступ на чтение к следующим свойствам и состоянию объекта:

  • Конфигурация устройств
  • Политика соответствия устройств требованиям
  • Уведомления о сообщениях

DeviceManagementConfiguration.ReadWrite.All

• Параметр "Включить доступ": чтение и запись конфигурации и политик устройства Microsoft Intune

• Разрешает те же операции, что и DeviceManagementConfiguration.Read.All

• Приложения также могут создавать, назначать, удалять и изменять следующие сущности:

  • Конфигурация устройств
  • Политика соответствия устройств требованиям
  • Уведомления о сообщениях

DeviceManagementManagedDevices.PrivilegedOperations.All

• Параметр "Включить Access": Выполнение удаленных действий, влияющих на пользователей, на устройствах Microsoft Intune

• Разрешает следующие удаленные действия на управляемом устройстве:

  • Прекращение использования
  • Очистка
  • Сброс и восстановление секретного кода
  • Удаленная блокировка
  • Включение и отключение режима пропажи
  • Очистить компьютер
  • Перезагрузка
  • Удаление пользователя с общего устройства

DeviceManagementManagedDevices.Read.All

• Параметр "Включить доступ": чтение устройств Microsoft Intune

• Предоставляет доступ на чтение к следующим свойствам и состоянию объекта:

  • Управляемое устройство
  • Категория устройства
  • Обнаруженное приложение
  • Удаленные действия
  • Сведения о вредоносных программах

DeviceManagementManagedDevices.ReadWrite.All

• Параметр "Включить Access": чтение и запись устройств Microsoft Intune

• Разрешает те же операции, что и DeviceManagementManagedDevices.Read.All

• Приложения также могут создавать, удалять и изменять следующие сущности:

  • Управляемое устройство
  • Категория устройства

• Также разрешены следующие удаленные действия:

  • Поиск устройств
  • Отключение блокировки активации
  • Запрос удаленной помощи

DeviceManagementRBAC.Read.All

• Параметр "Включить Access": чтение параметров RBAC Microsoft Intune

• Предоставляет доступ на чтение к следующим свойствам и состоянию объекта:

  • Назначения ролей
  • Определения ролей
  • Операции с ресурсами

DeviceManagementRBAC.ReadWrite.All

• Параметр "Включить Access": чтение и запись параметров RBAC в Microsoft Intune

• Разрешает те же операции, что и DeviceManagementRBAC.Read.All

• Приложения также могут создавать, назначать, удалять и изменять следующие сущности:

  • Назначения ролей
  • Определения ролей

DeviceManagementScripts.Read.All

• Параметр "Включить Access": чтение сценариев Microsoft Intune

• Приложения могут просматривать (читать) сценарий, в частности:

  • Сценарии оболочки устройства
  • Сценарии работоспособности устройства
  • Сценарии соответствия устройств требованиям
  • Сценарии оболочки с настраиваемым атрибутом устройства
  • Сценарии Управление устройствами

DeviceManagementScripts.ReadWrite.All

• Параметр "Включить Access": чтение и запись сценариев Microsoft Intune
  Позволяет выполнять те же операции, что и DeviceManagementScripts.Read.All

• Приложения могут создавать, обновлять и удалять сценарии, в частности следующие:

  • Сценарии оболочки устройства
  • Сценарии работоспособности устройства
  • Сценарии соответствия устройств требованиям
  • Сценарии оболочки с настраиваемым атрибутом устройства
  • Сценарии Управление устройствами

DeviceManagementServiceConfig.Read.All

• Параметр "Включить Access": ознакомьтесь с конфигурацией Microsoft Intune

• Предоставляет доступ на чтение к следующим свойствам и состоянию объекта:

  • Регистрация устройств
  • Сертификат push-уведомлений Apple
  • Программа регистрации устройств Apple
  • Программа корпоративных закупок Apple
  • Соединитель Exchange
  • Условия
  • Облачная PKI
  • Брендирование
  • Защита от угроз на мобильных устройствах

DeviceManagementServiceConfig.ReadWrite.All

• Параметр "Включить Access": чтение и запись Конфигурация Microsoft Intune

• Позволяет выполнять те же операции, что и DeviceManagementServiceConfig.Read.All_

• Приложения также могут настраивать следующие функции Intune:

  • Регистрация устройств
  • Сертификат push-уведомлений 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 Graph, и DeviceManagementManagedDevices.Read.All области разрешений.

• Учетные данные вашего клиента поддерживают административные функции.

• Код похож на показанные примеры.

Проверка подлинности Microsoft Entra ID в C#

В этом примере показано, как с помощью C# получить список устройств, связанных с вашей учетной записью Intune.

1. Запустите Visual Studio и создайте новый проект приложения консоли Visual C# (.NET Framework).

2. Введите имя проекта и при желании укажите другие детали.

   

3. Добавьте пакет NuGet Microsoft MSAL в проект с помощью обозревателя решений:

   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 Entra ID с помощью Microsoft Graph PowerShell

Сценарии PowerShell могут использовать модуль Microsoft Graph PowerShell для проверки подлинности. Дополнительные сведения см. в примерах использования Microsoft Graph PowerShell и Intune PowerShell.

Поддержка нескольких клиентов и партнеров

Если ваша организация поддерживает организации с собственными клиентами Microsoft Entra, вы можете разрешить клиентам использовать ваше приложение со своими клиентами.

Для этого:

1. Убедитесь, что учетная запись клиента существует в целевом клиенте Microsoft Entra.

2. Убедитесь, что учетная запись клиента позволяет пользователям регистрировать приложения (см. параметры пользователя).

3. Установите отношения между каждым клиентом.

   Для этого выполните одно из следующих действий:

   А. Используйте Центр партнеров Майкрософт для определения отношения с вашим клиентом и его адреса электронной почты.

   Б. Пригласите пользователя стать гостем вашего клиента.

Чтобы пригласить пользователя в качестве гостя вашего клиента, выполните следующие действия.

1. Выберите "Добавить гостя" на панели быстрых задач .

2. Введите адрес электронной почты клиента и (необязательно) добавьте персонализированное сообщение для приглашения.

3. Нажмите кнопку "Пригласить".

При этом пользователю будет отправлено приглашение.

Чтобы принять ваше приглашение, пользователю необходимо щелкнуть ссылку " Начало работы ".

После установления отношения (или принятия приглашения) добавьте учетную запись пользователя в роль каталога.

Не забудьте добавить пользователя на другие роли по мере необходимости. Например, чтобы разрешить пользователю управлять параметрами Intune, он должен быть администратором службы Intune как минимум.

Кроме того:

• Используется https://admin.microsoft.com для назначения лицензии Intune вашей учетной записи пользователя.

• Обновите код приложения, чтобы пройти проверку подлинности в домене клиента клиента Microsoft Entra, а не в своем собственном.

  Например, предположим, что вашим доменом клиента является contosopartner.onmicrosoft.comnorthwind.onmicrosoft.com, следует обновить код для проверки подлинности в клиенте клиента.

  Чтобы сделать это в приложении C# на основе предыдущего примера, вам нужно изменить значение переменной authority :

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

  на

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