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

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

В этой статье описывается, как программировать непосредственно протокол в приложении. По возможности рекомендуется использовать поддерживаемые библиотеки проверки подлинности Майкрософт (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.