Платформа удостоверений Майкрософт и поток предоставления разрешения на авторизацию устройства OAuth 2.0
Платформа удостоверений Майкрософт поддерживает предоставление авторизации устройства, которое позволяет пользователям входить на устройства с ограниченными входными данными, например смарт-телевизор, устройство Интернета вещей или принтер. Чтобы включить этот поток, устройство посещает веб-страницу в браузере на другом устройстве для входа. Когда пользователь выполнит вход, устройство сможет получить необходимые маркеры доступа и маркеры обновления.
В этой статье описывается, как программировать непосредственно протокол в приложении. По возможности рекомендуется использовать поддерживаемые библиотеки проверки подлинности Майкрософт (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
| Параметр | Условие | 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=535fb089-9ff3-47b6-9bfb-4f1264799865&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.