Платформа удостоверений Майкрософт и поток предоставления разрешения на авторизацию устройства OAuth 2.0

Статья
04/08/2024

Платформа удостоверений Майкрософт поддерживает предоставление авторизации устройства, которое позволяет пользователям входить на устройства с ограниченными входными данными, например смарт-телевизор, устройство Интернета вещей или принтер. Чтобы включить этот поток, устройство посещает веб-страницу в браузере на другом устройстве для входа. Когда пользователь выполнит вход, устройство сможет получить необходимые маркеры доступа и маркеры обновления.

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

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

Весь поток кода устройства показан на следующей схеме. Каждый шаг описан в этой статье.

Device code flow

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

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

С момента отправки запроса пользователь имеет 15 минут для входа. Это значение по умолчанию для expires_in. Запрос должен выполняться только в том случае, если пользователь указывает, что он готов к входу.

// Line breaks are for legibility only.

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile

Параметр	Условие	Description
`tenant`	Обязательное поле	Возможные значения: `/common`, `/consumers` или `/organizations`. Также можно указать клиент каталога, для которого требуется запросить разрешение, используя GUID или понятное имя.
`client_id`	Обязательное поле	Идентификатор приложения (клиента), который центр администрирования Microsoft Entra — Регистрация приложений, назначенный приложению.
`scope`	Обязательное поле	Разделенный пробелами список областей , для которого необходимо согласие пользователя.

Ответ авторизации устройства

Успешный ответ — это объект JSON, содержащий необходимые сведения для входа пользователя.

Параметр	Формат	Description
`device_code`	Строка	Длинная строка, используемая для проверки сеанса между клиентом и сервером авторизации. Клиент использует этот параметр для запроса маркера доступа от сервера авторизации.
`user_code`	Строка	Короткая строка, показанная пользователю для идентификации сеанса на дополнительном устройстве.
`verification_uri`	URI-адрес	URI, по которому пользователь должен перейти с помощью `user_code` для входа.
`expires_in`	INT	Количество секунд до окончания срока действия `device_code` и `user_code`.
`interval`	INT	Число секунд ожидания клиентом между опрашивающими запросами.
`message`	Строка	Понятная пользователю строка с инструкциями. Ее можно локализовать, включив параметр запроса в запросе формы `?mkt=xx-XX`, заменив соответствующий код языка и региональных параметров.

Примечание.

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

Проверка подлинности пользователя

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

Если пользователь проходит проверку подлинности с помощью личная учетная запись, используя /common или/consumers, им будет предложено выполнить вход еще раз, чтобы передать состояние проверки подлинности на устройство. Это связано с тем, что устройство не может получить доступ к файлам cookie пользователя. Им предлагается предоставить согласие на разрешения, запрошенные клиентом. Однако это не относится к рабочим или учебным учетным записям, используемым для проверки подлинности.

Хотя пользователь проходит проверку подлинности в verification_uri, клиент должен опросить конечную точку /token на наличие запрошенного токена с помощью device_code.

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

grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=00001111-aaaa-2222-bbbb-3333cccc4444&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...

Параметр	Обязательное поле	Описание
`tenant`	Обязательное поле	Тот же клиент или псевдоним клиента, что использовался в исходном запросе.
`grant_type`	Обязательное поле	Должен содержать значение `urn:ietf:params:oauth:grant-type:device_code`.
`client_id`	Обязательное поле	Должен соответствовать `client_id`, используемому в первоначальном запросе.
`device_code`	Обязательное поле	`device_code`, возвращаемый в запросе авторизации устройства.

Ожидаемые ошибки

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

Ошибка	Описание	Действие клиента
`authorization_pending`	Пользователь не завершил проверку подлинности, но не отменил поток.	Повторите запрос не менее чем через `interval` с.
`authorization_declined`	Пользователь отклонил запрос авторизации.	Остановка опроса и возврат в состояние без проверки подлинности.
`bad_verification_code`	Значение `device_code`, отправленное в конечную точку `/token`, не распознано.	Убедитесь, что клиент отправляет правильный `device_code` в запросе.
`expired_token`	Превышено `expires_in` значение, и проверка подлинности больше не возможна.`device_code`	Остановка опроса и возврат в состояние без проверки подлинности.

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

Успешный ответ маркера выглядит следующим образом:

{
    "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.

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