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

Статья
04/08/2024

Платформа удостоверений 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
&[email protected]
&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.

Поделиться через