Учетные данные владельца ресурса OAuth 2.0 для платформы удостоверений Майкрософт

  • Статья

Платформа удостоверений Microsoft поддерживает предоставление учетных данных владельца ресурса OAuth 2.0, что позволяет приложению выполнять вход на компьютер пользователя путем прямой обработки пароля. В этой статье описывается, как программировать непосредственно протокол в приложении. По возможности рекомендуется использовать поддерживаемые библиотеки проверки подлинности Майкрософт (MSAL) вместо получения маркеров и вызова защищенных веб-API. Также ознакомьтесь с примерами приложений, которые используют MSAL.

Предупреждение

Корпорация Майкрософт рекомендует не использовать поток ROPC. В большинстве случаев доступны и рекомендуются более безопасные альтернативы. Для этого потока нужен очень высокий уровень доверия в приложении, и он несет риски, которых нет в других потоках. Этот поток следует использовать только при невозможности использовать другие, более безопасные потоки.

Внимание

  • Платформа удостоверений Майкрософт поддерживает только грант ROPC в клиентах Microsoft Entra, а не личная учетная запись. Это означает, что придется использовать конечную точку клиента (https://login.microsoftonline.com/{TenantId_or_Name}) или конечную точку organizations.
  • Личные учетные записи, приглашенные в клиент Microsoft Entra, не могут использовать поток ROPC.
  • Учетные записи без паролей не могут войти в систему с помощью учетных данных владельца ресурса. То есть, такие функции, как вход по SMS, FIDO, а также приложение Authenticator не будут работать для этого потока. Используйте тип предоставления разрешения, отличный от ROPC, если приложению или пользователям требуются эти возможности.
  • Если пользователи должны использовать для входа в приложение многофакторную проверку подлинности (MFA), они будут заблокированы.
  • ROPC не поддерживается в сценариях федерации гибридных удостоверений (например, идентификатор Microsoft Entra и AD FS, используемые для проверки подлинности локальных учетных записей). Если пользователи полностью перенаправляются на страницу локального поставщика удостоверений, Microsoft Entra ID не сможет проверить имя пользователя и пароль для этого поставщика удостоверений. Однако с ROPC поддерживается сквозная проверка подлинности.
  • Существует следующее исключение из сценария гибридной федерации удостоверений: политика обнаружения домашней области со свойством AllowCloudPasswordValidation, для которого задано значение TRUE, позволит использовать поток ROPC для федеративных пользователей, если локальный пароль синхронизируется с облаком. Дополнительные сведения см. в разделе Включение прямой проверки подлинности ROPC для федеративных пользователей в устаревших приложениях.
  • Пароли с начальными или конечными пробелами не поддерживаются потоком ROPC.

Схема протокола

На следующей схеме показано представление потока ROPC.

Diagram showing the resource owner password credential flow

Запрос авторизации

Весь поток ROPC выполняется в рамках одного запроса. Он отправляет поставщику удостоверений идентификатор клиента и учетные данные пользователя, а в ответ получает от него маркеры. Перед этим клиент должен получить от пользователя адрес электронной почты (или другое имя участника-пользователя) и пароль. Сразу после успешного выполнения запроса клиент обязан безопасно удалить из памяти учетные данные пользователя. Ни в коем случае нельзя сохранять их.

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password
Параметр Условие Description
tenant Обязательное поле Клиент каталога, в который пользователь выполняет вход. Арендатора можно указать в виде GUID или понятного имени. Однако этот параметр не может иметь значение common или consumers, но может быть равен organizations.
client_id Обязательное поле Идентификатор приложения (клиента), который центр администрирования Microsoft Entra — Регистрация приложений страницу, назначенную вашему приложению.
grant_type Обязательное поле Должен иметь значениеpassword.
username Обязательное поле Адрес электронной почты пользователя.
password Обязательное поле Пароль пользователя.
scope Рекомендуемая конфигурация Разделенный пробелами список областей или разрешений, которые нужны приложению. В интерактивном потоке администратор или пользователь должен заранее дать согласие на эти области.
client_secret Иногда требуется client_secret или client_assertion невозможно добавить, если приложение является общедоступным клиентом. Если приложение является конфиденциальным клиентом, его нужно включить.
client_assertion Иногда требуется Другая форма client_secret, созданная с помощью сертификата. Дополнительные сведения см. в статье Учетные данные сертификатов.

Успешный ответ аутентификации

Ниже приведен пример успешного ответа маркера:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
Параметр Формат Description
token_type Строка Всегда имеет значение Bearer.
scope Строки, разделенные пробелами Если возвращен маркер доступа, этот параметр содержит список областей, для которых действует этот маркер.
expires_in INT Количество секунд, в течение которых действует предоставленный маркер доступа.
access_token Непрозрачная строка Выдается для запрошенных областей.
id_token JWT Выдается, если исходный параметр scope содержит область openid.
refresh_token Непрозрачная строка Выдается, если исходный параметр scope содержит offline_access.

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

Предупреждение

Не пытайтесь проверить или прочесть маркеры для любого API, который вам не принадлежит, включая маркеры в этом примере, в коде. Маркеры для служб Майкрософт могут использовать специальный формат, который не будет проверяться как JWT и может также быть зашифрован для пользователей-потребителей (учетная запись Майкрософт). Несмотря на то, что чтение маркеров является полезным средством отладки и обучения, не задавайте зависимости от него в коде или не опирайтесь на конкретные сведения о токенах, которые не предназначены для контролируемого вами API.

Отклик в случае ошибки

Если пользователь не указал правильное имя пользователя или пароль, либо клиент не получил требуемое согласие, аутентификация завершается ошибкой.

Ошибка Описание Действие клиента
invalid_grant Сбой аутентификации Учетные данные указаны неверно или у клиента отсутствует согласие для запрошенных областей. Если области не предоставлены, возвращается ошибка consent_required. Чтобы устранить эту ошибку, клиент должен отправить пользователю интерактивный запрос через веб-представление или браузер.
invalid_request Запрос был неправильно сформирован Тип предоставления разрешения не поддерживается для контекстов аутентификации /common или /consumers. Вместо этого используйте /organizations или идентификатор клиента.

Подробнее

Пример реализации потока ROPC см . в примере кода консольного приложения .NET на GitHub.