Использование API для добавления сторонних ЦС для SCEP в Intune

В Microsoft Intune можно добавить сторонние центры сертификации (ЦС), чтобы эти ЦС выпускали и проверяли сертификаты с помощью протокола SCEP. Добавление стороннего центра сертификации предоставляет общие сведения об этой функции и описывает задачи администратора в Intune.

Существуют также некоторые задачи разработчика, использующие библиотеку с открытым кодом, опубликованную корпорацией Майкрософт в GitHub.com. Библиотека включает API, который:

• Проверяет пароль SCEP, динамически создаваемый Intune.
• Уведомляет Intune о сертификатах, созданных на устройствах, отправляющих запросы SCEP.

С помощью этого API сторонний сервер SCEP интегрируется с Intune решением управления SCEP для устройств MDM. Библиотека абстрагирует от пользователей такие аспекты, как проверка подлинности, расположение службы и API службы ODATA Intune.

Решение для управления SCEP

Используя Intune, администраторы создают профили SCEP, а затем назначают их устройствам MDM. Профили SCEP включают такие параметры, как:

• URL-адрес сервера SCEP
• Доверенный корневой сертификат центра сертификации
• Атрибуты сертификата и многое другое

Устройствам, которые проверка с Intune, назначается профиль SCEP и настраиваются с помощью этих параметров. Intune создает динамически создаваемый пароль запроса SCEP, а затем назначается устройству.

Эта задача содержит следующее:

• Динамически создаваемый пароль запроса
• Сведения о параметрах, ожидаемых в запросе на подпись сертификата (CSR), который устройство выдает серверу SCEP
• Срок действия запроса

Intune шифрует эти сведения, подписывает зашифрованный BLOB-объект, а затем упаковывает эти сведения в пароль запроса SCEP.

Устройства, которые обращаются к серверу SCEP для запроса сертификата, а затем предоставляют этому запросу SCEP пароль. Сервер SCEP отправляет csr и зашифрованный пароль запроса SCEP Intune для проверки. Этот пароль запроса и CSR должны пройти проверку для сервера SCEP, чтобы выдать сертификат устройству. При проверке запроса SCEP выполняются следующие проверки:

• Проверяет сигнатуру зашифрованного большого двоичного объекта.
• Проверяет, является ли запрос активным и не истекшим сроком действия.
• Проверяет, что профиль по-прежнему предназначен для устройства.
• Проверяет, соответствуют ли свойства сертификата, запрошенные устройством в CSR, ожидаемым значениям.

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

Интеграция с Intune

Код для интеграции библиотеки с Intune SCEP доступен для скачивания в репозитории GitHub Microsoft/Intune-Resource-Access.

Интеграция библиотеки в продукты включает следующие действия. Для выполнения этих действий требуются знания о работе с репозиториями GitHub и создании решений и проектов в Visual Studio.

1. Регистрация для получения уведомлений из репозитория

2. Клонирование или скачивание репозитория

3. Перейдите к необходимой реализации библиотеки в папке \src\CsrValidation (https://github.com/Microsoft/Intune-Resource-Access/tree/develop/src/CsrValidation)

4. Создание библиотеки с помощью инструкций в файле README

5. Включите библиотеку в проект, который создает сервер SCEP

6. Выполните следующие задачи на сервере SCEP:

   • Разрешить администратору настроить идентификатор приложение Azure, ключ приложение Azure и идентификатор клиента (в этой статье), которые библиотека использует для проверки подлинности. Администраторы должны иметь возможность обновлять ключ приложение Azure.
   • Определение запросов SCEP, включающих пароль SCEP, созданный Intune
   • Использование библиотеки API проверки запросов для проверки паролей SCEP, созданных Intune.
   • Используйте API-интерфейсы уведомлений библиотеки, чтобы уведомлять Intune о сертификатах, выданных для запросов SCEP с Intune созданными паролями SCEP. Кроме того, уведомляйте Intune об ошибках, которые могут возникнуть при обработке этих запросов SCEP.
   • Убедитесь, что сервер регистрирует достаточно сведений, чтобы помочь администраторам устранить неполадки

7. Завершение тестирования интеграции (в этой статье) и устранение любых проблем

8. Предоставьте клиенту письменное руководство, объясняющее:

   • Как необходимо подключить сервер SCEP в Центре администрирования Microsoft Intune
   • Получение идентификатора приложение Azure и ключа приложение Azure, необходимых для настройки библиотеки

Подключение сервера SCEP в Azure

Для проверки подлинности в Intune серверу SCEP требуется идентификатор приложение Azure, ключ приложение Azure и идентификатор клиента. Серверу SCEP также требуется авторизация для доступа к API Intune.

Чтобы получить эти данные, администратор сервера SCEP входит в портал Azure, регистрирует приложение, предоставляет приложению разрешение на проверку запроса MICROSOFT INTUNE API\SCEP и разрешение Application.Read.All, создает ключ для приложения, а затем загружает идентификатор приложения, его ключ и идентификатор клиента.

Инструкции по регистрации приложения, получению идентификатора приложения, идентификатора клиента и ключей см. в статье Использование портала для создания Microsoft Entra приложения и субъекта-службы для доступа к ресурсам.

API библиотеки Java

Библиотека Java реализуется как проект Maven, который извлекает свои зависимости при сборке. API реализуется в com.microsoft.intune.scepvalidation пространстве имен классом IntuneScepServiceClient .

Класс IntuneScepServiceClient

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

Конструктор IntuneScepServiceClient

Подпись:

IntuneScepServiceClient(
    Properties configProperties)

Описание:

Создает экземпляр и настраивает IntuneScepServiceClient объект .

Параметры:

• configProperties — объект Properties, содержащий сведения о конфигурации клиента.

Конфигурация должна содержать следующие свойства:

• AAD_APP_ID="Идентификатор приложение Azure, полученный в процессе подключения"
• AAD_APP_KEY="Ключ приложение Azure, полученный в процессе подключения"
• TENANT="Идентификатор клиента, полученный в процессе подключения"
• PROVIDER_NAME_AND_VERSION="Информация, используемая для идентификации продукта и его версии"

Если для решения требуется прокси-сервер с проверкой подлинности или без проверки подлинности, можно добавить следующие свойства:

• PROXY_HOST="Узел, на котором размещен прокси-сервер".
• PROXY_PORT="Порт, прослушиваемый прокси-сервером".
• PROXY_USER="Имя пользователя, используемое, если прокси-сервер использует обычную проверку подлинности".
• PROXY_PASS="Пароль, используемый, если прокси-сервер использует обычную проверку подлинности".

Вызывает:

• IllegalArgumentException — возникает, если конструктор выполняется без соответствующего объекта свойства.

Заметки о безопасности Реализующий сервер SCEP должен защитить данные, введенные в свойствах конфигурации, сохраненных в хранилище, от незаконного изменения и раскрытия. Для защиты информации рекомендуется использовать правильные списки управления доступом (ACL) и шифрование.

Метод ValidateRequest

Подпись:

void ValidateRequest(
    String transactionId,
    String certificateRequest)

Описание:

Проверяет запрос сертификата SCEP.

Параметры:

• transactionId — идентификатор транзакции SCEP.
• certificateRequest — PKCS #10 Запрос сертификата Base64 в кодировке DER в виде строки.

Вызывает:

• IllegalArgumentException — вызывается при вызове с недопустимым параметром.
• IntuneScepServiceException — возникает, если обнаруживается, что запрос сертификата недопустим.
• Исключение — возникает при обнаружении непредвиденной ошибки

Заметки о безопасности:

• Если этот метод вызывает исключение, сервер SCEP не должен выдавать сертификат клиенту.
• Ошибки проверки запроса сертификата SCEP могут указывать на проблему в инфраструктуре Intune. Кроме того, они могут указать, что злоумышленник пытается получить сертификат.

Метод SendSuccessNotification

Подпись:

void SendSuccessNotification(
    String transactionId,
    String certificateRequest,
    String certThumbprint,
    String certSerialNumber,
    String certExpirationDate,
    String certIssuingAuthority)

Описание:

Уведомляет Intune о том, что сертификат создается в рамках обработки запроса SCEP.

Параметры:

• transactionId — идентификатор транзакции SCEP.
• certificateRequest — кодированный DER PKCS #10 Запрос сертификата Base64, закодированный в виде строки.
• certThumbprint — хэш SHA1 отпечатка подготовленного сертификата.
• certSerialNumber — серийный номер подготовленного сертификата.
• certExpirationDate — дата окончания срока действия подготовленного сертификата. Строка времени даты должна быть отформатирована как веб-время UTC (ГГГГ-ММ-ДДЧчч:мм:ss.sssTZD) ISO 8601.
• certIssuingAuthority — имя центра, выдающего сертификат.

Вызывает:

• IllegalArgumentException — вызывается при вызове с недопустимым параметром.
• IntuneScepServiceException — возникает, если обнаруживается, что запрос сертификата недопустим.
• Исключение — возникает при обнаружении непредвиденной ошибки.

Заметки о безопасности:

• Если этот метод вызывает исключение, сервер SCEP не должен выдавать сертификат клиенту.
• Ошибки проверки запроса сертификата SCEP могут указывать на проблему в инфраструктуре Intune. Кроме того, они могут указать, что злоумышленник пытается получить сертификат.

Метод SendFailureNotification

Подпись:

void SendFailureNotification(
    String transactionId,
    String certificateRequest,
    long  hResult,
    String errorDescription)

Описание:

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

Параметры:

• transactionId — идентификатор транзакции SCEP.
• certificateRequest — кодированный DER PKCS #10 Запрос сертификата Base64, закодированный в виде строки.
• hResult — код ошибки Win32, который лучше всего описывает возникшую ошибку. См . статью Коды ошибок Win32.
• errorDescription — описание обнаруженной ошибки.

Вызывает:

• IllegalArgumentException — вызывается при вызове с недопустимым параметром.
• IntuneScepServiceException — возникает, если обнаруживается, что запрос сертификата недопустим.
• Исключение — возникает при обнаружении непредвиденной ошибки.

Заметки о безопасности:

• Если этот метод вызывает исключение, сервер SCEP не должен выдавать сертификат клиенту.
• Ошибки проверки запроса сертификата SCEP могут указывать на проблему в инфраструктуре Intune. Кроме того, они могут указать, что злоумышленник пытается получить сертификат.

Метод SetSslSocketFactory

Подпись:

void SetSslSocketFactory(
    SSLSocketFactory factory)

Описание:

Используйте этот метод, чтобы сообщить клиенту о том, что при обмене данными с Intune он должен использовать указанную фабрику сокетов SSL (а не по умолчанию).

Параметры:

• factory — фабрика сокетов SSL, которую клиент должен использовать для HTTPS-запросов.

Вызывает:

• IllegalArgumentException — вызывается при вызове с недопустимым параметром.

Метод DownloadCARevocationRequests

Подпись:

List<CARevocationRequest> DownloadCARevocationRequests(String transactionId,
    int maxCARequestsToDownload, String issuerName)

Описание:

Скачивает список запросов на отзыв из Intune.

Исходный файл:

Расположение исходной папки GitHub находится в репозитории GitHub Microsoft/Intune-Resource-Access. IntuneRevocationClient.java является исходным файлом.

Параметры:

• transactionId — строка GUID, которая однозначно идентифицирует всю транзакцию, чтобы обеспечить корреляцию журналов при вызовах результатов загрузки и отправки. Сторонние вызывающие API должны выполнить следующие действия, чтобы создать идентификатор GUID:

String  transactionId = UUID.randomUUID.toString();

• maxCARequestsToDownload — максимальное количество запросов на отзыв для скачивания с Intune. Рекомендуется использовать значение верхней границы 100.

• issuerName — это значение совпадает с CertIssuingAuthority в вызове ScepRequestValidation . Максимальная длина строки — 256 символов.

Вызывает:

• IntuneClientException — возникает, если служба сообщает о сбое при обработке уведомления. Изучите код ошибки исключения.
• IllegalArgumentException — вызывается при вызове с недопустимым параметром.

Заметки о безопасности:

Требуются разрешения API. Дополнительные сведения и разрешения на регистрацию приложений см. в разделе Подключение сервера SCEP в Azure этой статьи.

Метод UploadRevocationResults

Подпись:

void UploadRevocationResults(

    String transactionId,

    List<CARevocationResult> revocationResults)

Описание:

Отправляет список результатов отзыва из стороннего ЦС в Intune.

Параметры:

• transactionId — строка GUID, которая однозначно идентифицирует всю транзакцию, чтобы обеспечить корреляцию журналов между вызовами результатов загрузки и отправки. Сторонние вызывающие API должны использовать тот же идентификатор transactionId из вызова DownloadCARevocationRequest.

• revocationResults — список объектов для отправки CARevocationResults в Intune.

Вызывает:

• IntuneClientException — возникает, если служба сообщает о сбое при обработке уведомления. Изучите код ошибки исключения.
• IllegalArgumentException — вызывается при вызове с недопустимым параметром.

C# API

API C# включает методы, используемые службой SCEP для скачивания и отправки результатов отзыва ЦС.

Метод DownloadCARevocationRequestsAsync

Подпись:

Task<List<CARevocationRequest>> DownloadCARevocationRequestsAsync(

    string transactionId,

    int maxCARevocationRequestsToDownload,

    string issuerName = null)

Описание:

Возвращает список запросов на отзыв ЦС.

Исходный файл:

Расположение исходной папки GitHub находится в репозитории GitHub Microsoft/Intune-Resource-Access. IntuneRevocationClient.cs — исходный файл.

Параметры:

• transactionId — строка GUID, которая однозначно идентифицирует всю транзакцию, чтобы обеспечить корреляцию журналов между вызовами результатов загрузки и отправки. Сторонние вызывающие API должны выполнить следующие действия, чтобы создать идентификатор GUID:

var transactionId = Guid.NewGuid().ToString();

• maxCARequestsToDownload — максимальное количество запросов на отзыв для скачивания с Intune. Рекомендуется использовать значение верхней границы 100.

• issuerName (необязательно) — это значение совпадает с CertIssuingAuthority в вызове ScepRequestValidation. Максимальная длина строки — 256 символов.

Вызывает:

• IntuneClientException — возникает, если служба сообщает о сбое при обработке уведомления. Изучите код ошибки исключения.
• IllegalArgumentException — вызывается при вызове с недопустимым параметром.

Заметки о безопасности:

Требуются разрешения API. Дополнительные сведения и разрешения на регистрацию приложений см. в разделе Подключение сервера SCEP в Azure этой статьи.

Метод UploadRevocationResults

Подпись:

Task UploadRevocationResultsAsync(

    string transactionId,

    List<CARevocationResult> requestResults)

Описание:

Отправляет список результатов отзыва из стороннего ЦС в Intune.

Параметры:

• transactionId — строка GUID, которая однозначно идентифицирует всю транзакцию, чтобы обеспечить корреляцию журналов между вызовами результатов загрузки и отправки. Сторонние вызывающие API должны использовать тот же идентификатор transactionId из вызова DownloadCARevocationRequestsAsync.

• revocationResults — список объектов для отправки CARevocationResults в Intune.

Вызывает:

• IntuneClientException — возникает, если служба сообщает о сбое при обработке уведомления. Изучите код ошибки исключения.

• IllegalArgumentException — вызывается при вызове с недопустимым параметром.

Тестирование интеграции

Проверка и проверка правильности интеграции решения с Intune является обязательной. Ниже перечислены общие сведения о шагах.

1. Настройте пробную учетную запись Intune.
2. Подключение сервера SCEP в портал Azure (в этой статье).
3. Настройте сервер SCEP с идентификаторами и ключами, созданными при подключении сервера SCEP.
4. Регистрация устройств для тестирования сценариев в матрице тестирования сценариев.
5. Создайте профиль доверенного корневого сертификата для тестового центра сертификации.
6. Создайте профили SCEP для тестирования сценариев, перечисленных в матрице тестирования сценариев.
7. Назначьте профили пользователям, которые зарегистрировали свои устройства.
8. Дождитесь синхронизации устройств с Intune. Или вручную синхронизируйте устройства.
9. Убедитесь, что на устройствах развернуты доверенный корневой сертификат и профили SCEP.
10. Убедитесь, что доверенный корневой сертификат установлен на всех устройствах.
11. Убедитесь, что сертификаты SCEP для назначенных профилей установлены на всех устройствах.
12. Убедитесь, что свойства установленных сертификатов соответствуют свойствам, заданным в профиле SCEP.
13. Убедитесь, что выданные сертификаты указаны правильно в Центре администрирования Intune

См. также

• Общие сведения о добавлении стороннего ЦС
• Настройка Intune
• Регистрация устройства
• Настройка профилей сертификатов SCEP (для этого сценария не используется настройка сервера и соединителя службы регистрации сетевых устройств Майкрософт)