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

Статья
2025-04-02

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

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

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

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

Поток кода устройства

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

Клиент должен сначала проверить сервер проверки подлинности для устройства и пользовательского кода, используемого для инициирования проверки подлинности. Клиент собирает этот запрос из конечной /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

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

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

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

Параметр	Формат	Описание
`device_code`	Струна	Длинная строка, используемая для проверки сеанса между клиентом и сервером авторизации. Клиент использует этот параметр для запроса маркера доступа с сервера авторизации.
`user_code`	Струна	Короткая строка, показанная пользователю для идентификации сеанса на дополнительном устройстве.
`verification_uri`	УРИ	Универсальный код ресурса (URI), к которым пользователь должен перейти, `user_code` чтобы войти в систему.
`expires_in`	инт	Количество секунд до окончания срока действия `device_code` и `user_code`.
`interval`	инт	Количество секунд, в течение которых клиент должен ждать между запросами опроса.
`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..."
}

Параметр	Формат	Описание
`token_type`	Струна	Всегда `Bearer`.
`scope`	Разделенные пробелами строки	Если маркер доступа был возвращен, в этом списке перечислены области, в которых маркер доступа действителен.
`expires_in`	инт	Количество секунд, в течение которых включен маркер доступа, действителен.
`access_token`	Непрозрачная строка	Выданы для областей , которые были запрошены.
`id_token`	JWT	Выдается, если исходный параметр `scope` включал область `openid`.
`refresh_token`	Непрозрачная строка	Выдано, если исходный параметр `scope` включал `offline_access`.

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

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

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