Защита API, используемого соединителем API в Внешняя идентификация Microsoft Entra потоках пользователей самостоятельной регистрации

Область применения: клиенты рабочей силы внешниеклиенты (дополнительные сведения)

При интеграции REST API в Внешняя идентификация Microsoft Entra потоке самостоятельной регистрации необходимо защитить конечную точку REST API с проверкой подлинности. Проверка подлинности REST API гарантирует, что только службы с соответствующими учетными данными, такими как идентификатор Microsoft Entra, могут вызывать вашу конечную точку. В этой статье описывается, как защитить REST API.

Необходимые компоненты

Выполните действия, описанные в разделе Руководство по добавлению соединителя API к процессу пользовательского входа.

Конечную точку API можно защитить либо с помощью обычной проверки подлинности через HTTP, либо с помощью проверки подлинности через HTTPS на основе сертификатов клиента. В любом случае вы предоставляете учетные данные, которые идентификатор Microsoft Entra использует при вызове конечной точки API. После этого ваша конечная точка API проверяет эти учетные данные и принимает решения относительно авторизации.

Обычная аутентификация через HTTP

Обычная аутентификация через HTTP определяется стандартом RFC 2617. Базовая проверка подлинности выполняется следующим образом: идентификатор Microsoft Entra отправляет HTTP-запрос с учетными данными клиента (username и password) в заголовке Authorization . Учетные данные имеют формат строки username:password в кодировке Base64. Затем ваш API проверяет эти значения для выполнения других решений об авторизации.

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

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор пользователя.
2. Обзор внешних> удостоверений.>
3. Выберите все соединители API и выберите соединитель API, который требуется настроить.
4. Для параметра Тип проверки подлинности выберите значение Обычная.
5. Укажите имя пользователя и пароль для конечной точки REST API.
6. Выберите Сохранить.

Аутентификация через HTTPS на основе сертификата клиента

Проверка подлинности на основе сертификата клиента — это взаимная проверка подлинности на основе сертификатов, где клиент, идентификатор Microsoft Entra, предоставляет сертификат клиента серверу для подтверждения его удостоверения. Это происходит в процессе приветствия SSL. API отвечает за проверку сертификатов, принадлежащих допустимому клиенту, например идентификатору Microsoft Entra, и принятию решений по авторизации. Сертификат клиента — это цифровой сертификат X.509.

Внимание

В рабочих средах сертификат должен быть подписан центром сертификации.

Создание сертификата

Вариант 1. Использование Azure Key Vault (рекомендуется)

Чтобы создать сертификат, можно использовать хранилище Azure Key Vault, которое поддерживает функции самозаверяющих сертификатов и интеграцию с поставщиками издателей сертификатов для использования подписанных сертификатов. Рекомендуется использовать следующие параметры.

• Тема: CN=<yourapiname>.<tenantname>.onmicrosoft.com
• Тип содержимого: PKCS #12
• Тип действия по времени существования: Email all contacts at a given percentage lifetime или Email all contacts a given number of days before expiry
• Тип ключа: RSA
• Размер ключа: 2048
• Экспортируемый закрытый ключ: Yes (чтобы иметь возможность экспортировать файл в формате .pfx)

Затем можно экспортировать сертификат.

Вариант 2. Подготовка самозаверяющего сертификата с помощью PowerShell

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

Windows

В Windows для создания сертификата используется командлет PowerShell New-SelfSignedCertificate.

1. Выполните следующую команду PowerShell, чтобы создать самозаверяющий сертификат. Измените аргумент -Subject, указав реальные значения приложения и имени арендатора Azure  AD B2C, например contosowebapp.contoso.onmicrosoft.com. Можно также скорректировать дату -NotAfter, чтобы указать другой срок действия сертификата.

   New-SelfSignedCertificate `
       -KeyExportPolicy Exportable `
       -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
       -KeyAlgorithm RSA `
       -KeyLength 2048 `
       -KeyUsage DigitalSignature `
       -NotAfter (Get-Date).AddMonths(12) `
       -CertStoreLocation "Cert:\CurrentUser\My"
   

2. На компьютере Windows найдите элемент Управление сертификатами пользователей и выберите его.

3. В области Сертификаты — текущий пользователь выберите Личное>Сертификаты>имя_приложения.имя_арендатора.onmicrosoft.com.

4. Выберите сертификат, а затем выберите Действие >Все задачи >Экспортировать.

5. Нажмите Далее>Да, экспортировать закрытый ключ>Далее.

6. Примите значения по умолчанию для параметра Формат экспортируемого файла и нажмите кнопку Далее.

7. Включите параметр Пароль, введите пароль для сертификата, а затем нажмите кнопку Далее.

8. Чтобы указать расположение для сохранения сертификата, нажмите кнопку Обзор и перейдите в нужный каталог.

9. В окне Сохранить как введите значение в поле Имя файла и нажмите кнопку Сохранить.

10. Выберите Далее>Готово.

Чтобы служба Azure AD B2C принимала пароль файла с расширением PFX, пароль необходимо зашифровать с помощью TripleDES-SHA1 в служебной программе экспорта хранилища сертификатов Windows, а не с помощью AES256-SHA256.

macOS

В macOS для создания сертификата используйте Помощник по сертификатам в Keychain Access.

1. Следуйте инструкциям по созданию самозаверяющих сертификатов в Keychain Access на Mac.
2. Выберите созданный сертификат в приложении Keychain Access на компьютере Mac.
3. Выберите Файл>Экспорт элементов.
4. Выберите имя файла для сохранения сертификата. Например, self-signed-certificate.p12.
5. Для параметра Формат файла установите значение Обмен персональными данными (.p12).
6. Выберите Сохранить.
7. Введите пароль в полях Пароль и Подтвердить.
8. Замените расширение файла на PFX. Например, self-signed-certificate.pfx.

Настройка соединителя API

Чтобы настроить соединитель API с проверкой подлинности с помощью сертификата клиента, выполните следующие действия.

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор пользователя.
2. Обзор внешних> удостоверений.>
3. Выберите все соединители API и выберите соединитель API, который требуется настроить.
4. Для параметра Тип проверки подлинности выберите значение Сертификат.
5. В поле Загрузить сертификат выберите PFX-файл сертификата с закрытым ключом.
6. В поле Введите пароль введите пароль сертификата.
7. Выберите Сохранить.

Выполнение решений об авторизации

Чтобы защитить конечные точки API, интерфейс API должен реализовывать авторизацию на основе отправленных клиентских сертификатов. Для Службы приложений Azure и Функций Azure см. сведения о том, как включить и проверить сертификат из кода API, в разделе Настройка взаимной проверки подлинности TLS. Вы также можете использовать Управление API Azure в качестве уровня перед любой службой API, чтобы проверить свойства сертификата клиента по нужным значениям.

Обновление сертификатов

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

Чтобы отправить новый сертификат в существующий соединитель API, выберите соединитель API в соединителях API и нажмите кнопку "Отправить новый сертификат". Последний отправленный сертификат, срок действия которого не истек, и дата начала которого была передана, будет автоматически использоваться идентификатором Microsoft Entra.

Проверка подлинности с использованием ключа API

Некоторые службы используют механизм "ключ API" для маскирования доступа к конечным точкам HTTP во время разработки, при этом требуется, чтобы вызывающий объект включал уникальный ключ в качестве HTTP-заголовка или параметра HTTP-запроса. Для Функций Azure это можно сделать, добавив code в качестве параметра запроса в URL-адрес конечной точки ваш соединитель API. Например, https://contoso.azurewebsites.net/api/endpoint?code=0123456789).

Это не механизм, который следует использовать только в рабочей среде. Поэтому всегда необходимо производить настройку для обычной аутентификации или аутентификации по сертификатам. Если вы не хотите реализовать какой-либо метод проверки подлинности (не рекомендуется) для целей разработки, вы можете выбрать обычную проверку подлинности в конфигурации соединителя API и использовать временные значения для username и password что API может игнорироваться при реализации правильной авторизации.

Следующие шаги

• Начните работу с наших примеров из кратких руководств.