Платформа удостоверений Майкрософт и поток кода авторизации OAuth 2.0
Тип предоставления кода авторизации OAuth 2.0 или поток кода авторизации позволяет клиентскому приложению получать авторизованный доступ к защищенным ресурсам, таким как веб-API. Для потока кода авторизации требуется пользовательский агент, который поддерживает перенаправление с сервера авторизации (платформа удостоверений Майкрософт) обратно в ваше приложение. Например, веб-браузер, классическое или мобильное приложение, управляемое пользователем для входа в ваше приложение и получения доступа к данным.
В этой статье описываются подробности низкоуровневого протокола, которые требуются только при ручном создании и отправке необработанных HTTP-запросов для реализации потока, что мы не рекомендуем делать. Вместо этого используйте библиотеку проверки подлинности, созданную и поддерживаемую Майкрософт. С ее помощью вы сможете получать маркеры безопасности и вызывать защищенные веб-API в своих приложениях.
Приложения, поддерживающие поток кода авторизации
Используйте поток кода авторизации в сочетании с ключом проверки для обмена кодами (PKCE) и OpenID Connect (OIDC) для получения маркеров доступа и маркеров ИД в следующих типах приложений:
- Одностраничное приложение (SPA)
- Стандартное (серверное) веб-приложение
- Настольные и мобильные приложения
Сведения о протоколе
Описание потока кода авторизации OAuth 2.0 см. в разделе 4.1 спецификации OAuth 2.0. Приложения, использующие поток кода авторизации OAuth 2.0, получают access_token для включения в запросы к ресурсам, защищенным платформой удостоверений Майкрософт (обычно API). Приложения также могут запрашивать новые идентификаторы и маркеры доступа для ранее прошедших проверку подлинности сущностей с помощью механизма обновления.
На этой диаграмме показано высокоуровневое представление потока проверки подлинности:
URI перенаправления для одностраничных приложений (SPA)
URI перенаправления для SPA, которые используют поток кода авторизации, требуют специальной конфигурации.
- Добавьте URI перенаправления, который поддерживает поток кода авторизации с PKCE и общий доступ к ресурсам независимо от источника (CORS): выполните инструкции из раздела URI перенаправления: MSAL.js 2.0 с потоком кода авторизации.
-
Обновите URI перенаправления: Установите URI перенаправления от
typeкspa, используя редактор манифеста приложения в Центре администрирования Microsoft Entra.
Тип перенаправления spa обеспечивает обратную совместимость с неявным потоком. Приложения, в настоящее время использующие неявный поток для получения токенов, могут переноситься в spa тип URI перенаправления без проблем и продолжать использовать неявный поток. Несмотря на эту обратную совместимость, мы рекомендуем использовать поток авторизационного кода с PKCE для SPA.
Если вы попытаетесь использовать поток кода авторизации без настройки CORS для URI перенаправления, эта ошибка появится в консоли:
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/oauth2/v2.0/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
В таком случае перейдите к регистрации приложения и обновите URI перенаправления для приложения на тип spa.
Приложения не могут использовать URI перенаправления spa с потоками, не являющимися SPA, например с потоками собственных приложений или потоками учетных данных клиента. Чтобы обеспечить безопасность и соблюдение лучших практик, платформа удостоверений Microsoft вернёт ошибку, если вы попытаетесь использовать URI перенаправления spa без заголовка Origin. Аналогичным образом платформа удостоверений Microsoft также предотвращает использование учетных данных клиента при наличии заголовка Origin, чтобы гарантировать, что конфиденциальные данные не будут использоваться в браузере.
Запрос кода авторизации
Поток кода авторизации начинается с того, что клиент направляет пользователя к конечной точке /authorize . В этом примере запроса клиент запрашивает openidoffline_accessи https://graph.microsoft.com/mail.read разрешения от пользователя.
Некоторые разрешения имеют только администраторы, например запись данных в каталог организации с помощью Directory.ReadWrite.All. Если приложение запрашивает доступ к одному из таких разрешений у корпоративного пользователя, появится сообщение об ошибке со сведениями о том, что этот пользователь не может предоставить разрешения приложению. Чтобы запросить доступ к областям только для администраторов, необходимо запросить их непосредственно у глобального администратора. Дополнительные сведения см. в статье Разрешения, предназначенные только для администраторов.
Если не указано иное, для необязательных параметров отсутствуют значения по умолчанию. Но для запроса, в котором отсутствуют необязательные параметры, определено поведение по умолчанию. По умолчанию выполняется вход в систему для одного текущего пользователя, при нескольких пользователях отображается окно выбора учетной записи, а если никто не вошел в систему, то отображается страница входа.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Параметр | Обязательный/необязательный | Описание |
|---|---|---|
tenant |
обязательно | Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента. В гостевых сценариях, когда пользователь из одного арендатора выполняет вход в другой, необходимо предоставить идентификатор арендатора, чтобы войти в целевой ресурс. Дополнительные сведения см. в разделе "Конечные точки". |
client_id |
обязательно | Идентификатор приложения (клиента), который центр администрирования Microsoft Entra — Регистрация приложений присвоил вашему приложению. |
response_type |
обязательно | Должен содержать code для потока кода авторизации. Может также включать id_token или token при использовании гибридного потока. |
redirect_uri |
обязательно | Конечная точка redirect_uri вашего приложения, где могут отправляться и получаться ответы на запросы проверки подлинности. Он должен точно соответствовать одному из URI перенаправления, зарегистрированных в Центре администрирования Microsoft Entra, за исключением того, что он должен быть закодирован URL-адресом. Для собственных и мобильных приложений следует использовать одно из рекомендуемых значений — https://login.microsoftonline.com/common/oauth2/nativeclient (для приложений, использующих встроенные браузеры) или http://localhost (для приложений, использующих системные браузеры). |
scope |
обязательно | Разделенный пробелами список областей , для которого необходимо согласие пользователя. Для части запроса /authorize этот параметр может охватывать несколько ресурсов. Это значение позволяет приложению получить согласие на несколько веб-API, которые необходимо вызвать. |
response_mode |
рекомендуется | **
Указывает, как платформа удостоверений должна вернуть запрошенный токен для вашего приложения. Поддерживаемые значения: - query: значение по умолчанию при запросе токена доступа. Предоставляет код в качестве параметра строки запроса в URI перенаправления. Параметр query не поддерживается при запросе токена идентификатора с использованием имплиситного потока. - fragment: значение по умолчанию при запросе маркера идентификации с помощью неявного потока. Поддерживается также при запросе только кода.- form_post: выполняет запрос POST, который содержит код для URI перенаправления. Поддерживается при запросе кода. |
state |
рекомендуется | Значение, включенное в запрос, которое также возвращается в ответе токена. Это может быть строка любого контента, который вы пожелаете. Как правило, для предотвращения подделки межсайтовых запросовиспользуется генерируемое случайным образом уникальное значение. Это значение также может включать информацию о состоянии пользователя в приложении перед созданием запроса на проверку подлинности. Например, оно может кодировать страницу или представление, на котором они находились. |
prompt |
необязательно | Указывает требуемый тип взаимодействия с пользователем. Допустимые значения: login, none, consent и select_account.- prompt=login принуждает пользователя вводить учетные данные по запросу, что отменяет единый вход.- prompt=none является противоположностью. Это гарантирует, что для пользователя не будут выводиться интерактивные запросы. Если запрос невозможно выполнить бесшумно, используя единый вход, платформа удостоверений Майкрософт возвращает ошибку interaction_required.- prompt=consent вызывает диалоговое окно согласия OAuth после входа пользователя, запрашивая у него разрешения для приложения.- prompt=select_account прерывает процесс единого входа в систему, предоставляя интерфейс выбора учетной записи из списка всех учетных записей в текущей сессии или среди любых сохранённых учетных записей, либо возможность выбрать совершенно другую учетную запись. |
login_hint |
необязательно | Этот параметр можно применять для предварительного заполнения полей имени пользователя и электронного адреса на странице входа пользователя. Приложения могут использовать этот параметр во время повторной проверки подлинности после извлечения необязательного login_hintутверждения из предыдущего входа. |
domain_hint |
необязательно | Если указан этот параметр, приложение пропускает процесс обнаружения на основе электронной почты, который нужно проходить на странице входа в приложение. Это несколько упрощает взаимодействие с пользователем. Например, отправка их в федеративный поставщик удостоверений. Приложения могут использовать этот параметр во время повторной аутентификации, извлекая tid из предыдущего сеанса входа. |
code_challenge |
рекомендованный/обязательный | Используется для обеспечения безопасности предоставления кодов авторизации с помощью Proof Key for Code Exchange (PKCE). Является обязательным, если указан параметр code_challenge_method. Дополнительную информацию см. в PKCE RFC. Этот параметр рекомендуется для всех типов приложений (как общедоступных, так и для конфиденциальных клиентов) и требуется платформой удостоверений Майкрософт для одностраничных приложений, использующих поток кода авторизации. |
code_challenge_method |
рекомендованный/обязательный | Метод, используемый для кодирования code_verifier в параметре code_challenge. Он ДОЛЖЕН быть равен S256, но спецификация позволяет использовать plain, если клиент не поддерживает SHA256. Если этот параметр не указан, для code_challenge принимается формат открытого текста, если задано значение code_challenge. Платформа удостоверений Майкрософт поддерживает как plain, так и S256. Для получения дополнительной информации см. PKCE RFC. Этот параметр необходим для одностраничных приложений, использующих поток кода авторизации. |
На текущем этапе пользователю предлагается ввести учетные данные и завершить аутентификацию. Платформа удостоверений Майкрософт также проверяет, согласился ли пользователь предоставить разрешения, указанные в параметре запроса scope. Если пользователь не предоставил ни одного из данных разрешений, система запрашивает у пользователя согласие на необходимые разрешения. Для получения дополнительной информации см. разрешения и согласие в идентификационной платформе Майкрософт.
После того как пользователь пройдет проверку подлинности и предоставит разрешения, платформа удостоверений Майкрософт вернет приложению ответ на указанный redirect_uri с помощью метода, указанного в параметре response_mode.
Успешный ответ
В этом примере показан успешный ответ с помощью response_mode=query:
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Параметр | Описание |
|---|---|
code |
Маркер authorization_code, запрошенный приложением. Приложение может использовать код авторизации для целевого ресурса, чтобы запросить токен доступа. Коды авторизации имеют небольшой срок действия. Обычно они истекают через примерно 10 минут. |
state |
Если запрос содержит параметр state, то в ответе должно отображаться то же значение. Приложение должно убедиться, что значения параметра state в запросе и отклике идентичны. |
Вы также можете получить токен идентификатора, если вы его запросите и в регистрации приложения включено неявное разрешение. Такое поведение иногда называют гибридным потоком. Он используется такими платформами, как ASP.NET.
Отклик в случае ошибки
Сообщения об ошибках также можно отправлять на redirect_uri , чтобы приложение обрабатывало их должным образом:
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. Эта часть ошибки предоставляется таким образом, чтобы приложение реагировало соответствующим образом на ошибку, но не объясняет подробно, почему произошла ошибка. |
error_description |
Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности. Эта часть ошибки содержит большую часть полезной информации о причинах возникновения ошибки. |
Коды ошибок на конечной точке авторизации
В следующей таблице описаны различные коды ошибок, которые могут возвращаться в параметре ответа с ошибкой error.
| Код ошибки | Описание | Действие клиента |
|---|---|---|
invalid_request |
Ошибка протокола, например отсутствует обязательный параметр. | Исправьте запрос и отправьте его повторно. Это ошибка разработки, которая обычно определяется во время первоначального тестирования. |
unauthorized_client |
Клиентскому приложению не разрешено запрашивать код авторизации. | Эта ошибка обычно возникает, когда клиентское приложение не зарегистрировано в идентификаторе Microsoft Entra или не добавляется в клиент Microsoft Entra пользователя. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в идентификатор Microsoft Entra. |
access_denied |
Владелец ресурса отказал в согласии | Клиентское приложение может уведомить пользователя, что для продолжения работы необходимо согласие пользователя. |
unsupported_response_type |
Сервер авторизации не поддерживает тип ответа в запросе. | Исправьте запрос и отправьте его повторно. Это ошибка разработки, которая обычно определяется во время первоначального тестирования. В гибридном потоке эта ошибка указывает, что необходимо включить настройку неявного предоставления токена ID в регистрации клиентского приложения. |
server_error |
Сервер обнаружил непредвиденную ошибку. | Повторите запрос. Эти ошибки могут возникать в связи с временными условиями. Из клиентского приложения может поступить сообщение о том, что его ответ задерживается из-за временной ошибки. |
temporarily_unavailable |
Сервер временно занят и не может обработать запрос. | Повторите запрос. Из клиентского приложения может поступить сообщение о том, что его ответ задерживается из-за временного состояния. |
invalid_resource |
Целевой ресурс недопустим, так как он не существует, идентификатор Microsoft Entra id не может найти его или неправильно настроен. | Это означает, что ресурс не существует или не настроен в клиенте. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в идентификатор Microsoft Entra. |
login_required |
Слишком много пользователей или ни одного пользователя не найдено. | Клиент запросил автоматическую аутентификацию (prompt=none), но одного пользователя не удалось найти. Эта ошибка может означать, что в сеансе активно несколько пользователей или пользователи отсутствуют. Эта ошибка принимает во внимание выбранного арендатора. Например, если есть две активные учетные записи Microsoft Entra и одна учетная запись Майкрософт, и выбран consumers, то бесшумная проверка подлинности работает. |
interaction_required |
Для запроса требуется взаимодействие с пользователем. | Требуется дополнительный шаг аутентификации или предоставление согласия. Повторите запрос без prompt=none. |
Запрос маркера идентификатора или гибридного потока
Чтобы узнать, кем является пользователь, прежде чем активировать код авторизации, приложение зачастую также запрашивает маркер идентификатора при запросе кода авторизации. Этот подход называется гибридным потоком, так как он смешивает OIDC с потоком кода авторизации OAuth2.
Гибридный поток обычно используется в веб-приложениях для отображения страницы пользователю без блокировки при получении кода, особенно в ASP.NET. Данная модель позволяет снизить задержку как в одностраничных, так и в традиционных веб-приложениях.
Гибридный поток аналогичен потоку кода авторизации, описанному ранее, но с тремя дополнениями. Все эти дополнения необходимы для запроса маркера идентификации: новые области, новый тип ответа (response_type) и новый параметр запроса nonce.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Обновленный параметр | Обязательный/необязательный | Описание |
|---|---|---|
response_type |
обязательно | Добавив id_token, вы указываете серверу, что приложение должно иметь маркер идентификатора в ответе от конечной точки /authorize. |
scope |
обязательно | Для маркеров идентификаторов необходимо обновить этот параметр, чтобы включить области маркеров идентификаторов — openid и при необходимости profile и email. |
nonce |
обязательно | Значение, включенное в запрос и созданное приложением, которое включено в результирующий id_token в качестве утверждения. Приложение может проверить это значение для предотвращения атак повторного использования токена. Это значение обычно представляет собой случайную уникальную строку, которую можно использовать для определения источника запроса. |
response_mode |
рекомендуется | Указывает метод, с помощью которого результирующий маркер будет отправлен приложению. Значение по умолчанию — query это просто код авторизации, но fragment, если запрос содержит id_tokenresponse_type, как указано в спецификации OpenID. Мы рекомендуем приложениям использовать form_post, особенно при использовании http://localhost в качестве URI для перенаправления. |
Использование fragment в качестве режима реагирования вызывает проблемы для веб-приложений, считывающих код из перенаправления. Браузеры не передают фрагмент на веб-сервер. В таких ситуациях приложения должны использовать режим ответа form_post, чтобы обеспечить отправку всех данных на сервер.
Успешный ответ
В этом примере показан успешный ответ с помощью response_mode=fragment:
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| Параметр | Описание |
|---|---|
code |
Запрашиваемый приложением код авторизации. Приложение может использовать код авторизации для запроса токена доступа для целевого ресурса. Срок действия кодов авторизации мал и обычно истекает по прошествии порядка 10 минут. |
id_token |
Маркер идентификатора для пользователя, выданный посредством неявного предоставления. Содержит специальное утверждение c_hash, которое является хэшем code в том же запросе. |
state |
Если запрос содержит параметр state, то в ответе должно отображаться то же значение. Приложение должно убедиться, что значения параметра state в запросе и отклике идентичны. |
Активация кода для токена доступа
Все конфиденциальные клиенты имеют возможность использовать секреты клиента или учетные данные сертификата. Симметричные общие секреты создаются платформой удостоверений Майкрософт. Учетные данные сертификата — это асимметричные ключи, отправленные разработчиком. Дополнительные сведения см. в статье Учетные данные сертификата аутентификации приложения платформы идентификации Microsoft.
Для обеспечения лучшей безопасности рекомендуется использовать учетные данные сертификата. Общедоступные клиенты, которые включают в себя собственные приложения и одностраничные приложения, не должны использовать секреты или сертификаты при активации кода авторизации. Всегда следите за тем, чтобы идентификаторы URI перенаправления включали тип приложения и были уникальными.
Запросить токен доступа с помощью "client_secret"
Теперь, когда вы получили authorization_code и у вас есть разрешение от пользователя, вы можете обменять code на access_token к ресурсу. Для получения code отправьте запрос POST к конечной точке /token:
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| Параметр | Требуется/не требуется | Описание |
|---|---|---|
tenant |
обязательно | Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента. Дополнительные сведения см. в разделе "Конечные точки". |
client_id |
обязательно | Идентификатор приложения (клиента), который назначила вашей программе страница центр администрирования Microsoft Entra – Регистрации приложений. |
scope |
необязательно | Список областей, разделённый пробелами. Все области видимости должны принадлежать одному ресурсу, включая области видимости OIDC (profile, openid, email). Дополнительную информацию см. в разделе разрешения и согласие на платформе идентификации Майкрософт. Этот параметр является расширением Microsoft для потока авторизации с кодом, предназначенным для того, чтобы разрешить приложениям объявлять ресурсы, для которых они хотят получить токен во время получения токена. |
code |
обязательно | Значение authorization_code, полученное в первой части потока. |
redirect_uri |
обязательно | То же значение redirect_uri, что использовалось для получения authorization_code. |
grant_type |
обязательно | Должен быть authorization_code для потока кода авторизации. |
code_verifier |
рекомендуется | Тот же code_verifier, который использовался для получения кода авторизации. Является обязательным, если в запросе на код авторизации использовался PKCE. Дополнительные сведения см. в PKCE RFC. |
client_secret |
обязательный для конфиденциальных веб-приложений | Секрет приложения, созданный на портале регистрации вашего приложения. Не используйте секрет приложения в собственном приложении или одностраничном приложении, поскольку client_secret невозможно надежно сохранить на устройствах или на веб-страницах. Он требуется для веб-приложений и веб-API с возможностью безопасного хранения client_secret на сервере. Как и все описанные здесь параметры, секрет клиента должен быть закодирован в виде URL-адреса перед отправкой. Этот шаг выполняется пакетом SDK. Дополнительные сведения о кодировке URI см. в разделе Спецификация универсального синтаксиса URI. Также поддерживается шаблон базовой проверки подлинности вместо предоставления учетных данных в заголовке авторизации согласно RFC 6749. |
Запросите токен доступа с учетными данными сертификата
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| Параметр | Обязательный/необязательный | Описание |
|---|---|---|
tenant |
обязательно | Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента. Дополнительные сведения см. в разделе Конечные точки. |
client_id |
обязательно | Идентификатор приложения (клиента), который страница Регистрация приложений в центре администрирования Microsoft Entra присвоила вашему приложению. |
scope |
необязательно | Список областей, разделённых пробелами. Все области должны принадлежать одному ресурсу, включая области OIDC (profile, openid, email). Дополнительные сведения см. в статье разрешения, согласие и области действия. Этот параметр является расширением Microsoft для потока кода авторизации. Это расширение позволяет приложениям указывать ресурс, для которого они хотят получить токен при его погашении. |
code |
обязательно | Значение authorization_code, полученное в первой части потока. |
redirect_uri |
обязательно | То же значение redirect_uri, что использовалось для получения authorization_code. |
grant_type |
обязательно | Должен быть authorization_code для потока кода авторизации. |
code_verifier |
рекомендуется | Для получения authorization_code был использован тот же code_verifier. Является обязательным, если в запросе на код авторизации использовался PKCE. Дополнительную информацию см. в документе PKCE RFC. |
client_assertion_type |
обязательный для конфиденциальных веб-приложений | Для использования учетных данных сертификата необходимо задать значение urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion |
обязательный для конфиденциальных веб-приложений | Утверждение, представляющее собой JSON Web Token (JWT), которое необходимо создать и подписать при помощи сертификата, который вы зарегистрировали в качестве учетных данных для вашего приложения. Ознакомьтесь с информацией об учетных данных сертификата, чтобы узнать, как зарегистрировать сертификат и задать формат утверждения. |
Обратите внимание на то, что параметры являются такими же, как и при использовании запроса с помощью общего секрета, за исключением параметра client_secret, который заменяется двумя параметрами: client_assertion_type и client_assertion.
Успешный ответ
Этот пример показывает успешный ответ токена.
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| Параметр | Описание |
|---|---|
access_token |
Запрашиваемый маркер доступа. Приложение может использовать этот маркер для аутентификации в защищенном ресурсе, таком как веб-API. |
token_type |
Указывает значение типа токена. Единственный тип Bearer, поддерживаемый идентификатором Microsoft Entra ID. |
expires_in |
Сколько времени токен доступа будет действителен (в секундах). |
scope |
Области, для которых действителен access_token. Необязательно. Этот параметр не является стандартным, и, если он опущен, токен будет использоваться для областей, запрошенных на начальном этапе потока. |
refresh_token |
Маркер обновления OAuth 2.0. Приложение может использовать этот маркер, чтобы получать другие маркеры доступа после истечения срока действия текущего маркера. Маркеры обновления имеют большой срок действия. Они могут поддерживать доступ к ресурсам в течение продолжительных периодов. Дополнительные сведения об обновлении маркера доступа см. в разделе Обновление маркера доступа далее в этой статье. Примечание. Предоставляется, только если подан запрос на область offline_access. |
id_token |
Маркер JSON Web Token. Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Приложение может кэшировать значения и отображать их, а конфиденциальные клиенты могут использовать этот маркер для авторизации. Для получения дополнительной информации о id_tokens см. id_token reference. Примечание. Предоставляется, только если подан запрос на область openid. |
Отклик в случае ошибки
Этот пример представляет собой сообщение об ошибке:
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, характерных для службы маркеров безопасности (STS), которые могут помочь при диагностике. |
timestamp |
Время возникновения ошибки. |
trace_id |
Уникальный идентификатор для запроса, который может помочь при диагностике. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Коды ошибок конечных точек токенов
| Код ошибки | Описание | Действие клиента |
|---|---|---|
invalid_request |
Ошибка протокола, например отсутствует обязательный параметр. | Исправьте регистрацию запроса или приложения и отправьте запрос повторно. |
invalid_grant |
Неверный или устаревший код авторизации или верификатор PKCE. | Повторите запрос к конечной точке /authorize и убедитесь, что параметр code_verifier указан правильно. |
unauthorized_client |
У аутентифицированного клиента нет прав на использование этого типа разрешения на авторизацию. | Эта ошибка обычно возникает, когда клиентское приложение не зарегистрировано в идентификаторе Microsoft Entra или не добавляется в клиент Microsoft Entra пользователя. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в идентификатор Microsoft Entra. |
invalid_client |
Сбой проверки подлинности клиента. | Недействительные учетные данные клиента. Чтобы устранить эту проблему, администратор приложения обновляет учетные данные. |
unsupported_grant_type |
Сервер авторизации не поддерживает тип предоставления авторизации. | Измените тип предоставления в запросе. Ошибка этого типа должна происходить только во время разработки, и ее должны обнаружить при первоначальном тестировании. |
invalid_resource |
Целевой ресурс недопустим, так как он не существует, идентификатор Microsoft Entra id не может найти его или неправильно настроен. | Этот код означает, что ресурс, если он существует, не настроен в клиенте. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в идентификатор Microsoft Entra. |
interaction_required |
Не является стандартным, поскольку спецификация OIDC обращается к этому коду только на конечной точке /authorize. Для запроса требуется взаимодействие с пользователем. К примеру, требуется другой шаг проверки подлинности. |
Повторите запрос /authorize с теми же областями. |
temporarily_unavailable |
Сервер временно занят и не может обработать запрос. | Повторите запрос через некоторое время. Из клиентского приложения может поступить сообщение о том, что его ответ задерживается из-за временного состояния. |
consent_required |
Для запроса требуется согласие пользователя. Эта ошибка не является стандартной. Обычно он возвращается только для конечной точки /authorize согласно спецификациям OIDC. Возвращается при использовании параметра scope в потоке активации кода, на запрос которого у клиентского приложения нет разрешений. |
Клиент должен отправить пользователя обратно на конечную точку /authorize с правильной областью, чтобы активировать согласие. |
invalid_scope |
Приложение запрашивает недопустимые права доступа. | Измените значение параметра scope в запросе проверки подлинности на допустимое значение. |
Примечание.
В одностраничных приложениях может отображаться ошибка invalid_request, указывающая на то, что активация токена между источниками разрешена только для клиентов типа "Одностраничное приложение". Это означает, что URI перенаправления, используемый для запроса токена, не был отмечен как URI перенаправления spa. Дополнительные сведения о том, как включить этот поток, см. в действиях по регистрации приложений.
Используйте маркер доступа
Теперь, когда вы успешно приобрели access_token, вы можете использовать токен в запросах к веб-API, включив его в заголовок Authorization.
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Обновление токена доступа
Маркеры доступа имеют небольшой срок действия. Обновите их после истечения срока действия, чтобы сохранить доступ к ресурсам. Для этого нужно отправить еще один запрос POST в конечную точку /token, указав refresh_token вместо code. Токены обновления действительны для всех разрешений, на которые клиент уже получил согласие. Например, маркер обновления, выданный в запросе scope=mail.read, можно использовать для запроса нового маркера доступа для scope=api://contoso.com/api/UseResource.
Для маркеров обновления для веб-приложений и собственных приложений не указано время существования. Обычно у маркеров обновления относительно продолжительный срок действия. Но в некоторых случаях маркер обновления оказывается устаревшим или отозванным или не имеет достаточных привилегий для этого действия. Ваше приложение должно ожидать и обрабатывать ошибки, возвращаемые службой выдачи токенов. Одностраничные приложения получают маркер с временем жизни 24 часа, что требует новой проверки подлинности каждый день. Это можно сделать в окне iframe без вмешательства пользователя, если включены сторонние файлы cookie. Но они должны выполняться в рамках фрейма верхнего уровня (полная навигация по страницам или всплывающее окно) в браузерах без сторонних файлов cookie, таких как Safari.
Токены обновления не аннулируются, если используются для получения новых токенов доступа. Ожидается, что вы удалите старый токен обновления. Спецификация OAuth 2.0 говорит: "Сервер авторизации может выдавать новый маркер обновления, в этом случае клиент должен отменить старый маркер обновления и заменить его новым маркером обновления. Сервер авторизации может отозвать старый маркер обновления после выпуска нового маркера обновления для клиента".
Внимание
Для маркеров обновления, отправленных в URI перенаправления, зарегистрированного как spa, срок действия маркера обновления истечет через 24 часа. Дополнительные маркеры обновления, полученные с помощью начального маркера обновления, наследуют это время действия, поэтому приложения следует подготовить к повторному выполнению потока кода аутентификации с помощью интерактивной аутентификации, чтобы получать новый маркер обновления раз в 24 часа. Пользователям не нужно вводить учетные данные. Как правило, они даже не видят никаких признаков взаимодействия — только перезагрузку приложения. Чтобы увидеть сеанс входа, браузер должен посетить страницу входа во фрейме верхнего уровня. Это обусловлено функциями обеспечения конфиденциальности в браузерах, блокирующих сторонние файлы cookie.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| Параметр | Тип | Описание |
|---|---|---|
tenant |
обязательно | Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента. Дополнительные сведения см. в разделе "Конечные точки". |
client_id |
обязательно | Идентификатор приложения (клиента), который был назначен вашему приложению в процессе центра администрирования Microsoft Entra – Регистрация приложений. |
grant_type |
обязательно | Должен быть refresh_token для этого участка потока кода авторизации. |
scope |
необязательно | Список областей с разделителями-пробелами. Области, запрашиваемые на этом участке, должны быть эквивалентны областям, запрашиваемым на исходном участке запроса authorization_code, или являться их подмножеством. Если области, указанные в этом запросе, охватывают несколько серверов ресурсов, платформа удостоверений Майкрософт вернет маркер ресурса, указанного в первой области. Дополнительную информацию см. в разделе Разрешения и согласие на платформе удостоверений Microsoft. |
refresh_token |
обязательно |
refresh_token, который вы приобрели на втором этапе процесса. |
client_secret |
необходим для веб-приложений | Секрет вашего приложения, созданный на портале регистрации приложений. Его не следует использовать в собственном приложении, так как client_secret нельзя надежно хранить на устройствах. Он требуется для веб-приложений и веб-API с возможностью безопасного хранения client_secret на сервере. Этот секрет должен быть закодирован в виде URL-адреса. Дополнительные сведения см. в разделе Спецификация универсального синтаксиса URI. |
Успешный ответ
Пример успешного ответа токена:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| Параметр | Описание |
|---|---|
access_token |
Запрашиваемый маркер доступа. Приложение может использовать этот маркер для аутентификации в защищенном ресурсе, таком как веб-API. |
token_type |
Указывает значение типа токена. Единственный тип, поддерживаемый Microsoft Entra ID, — это Bearer. |
expires_in |
Срок действия токена доступа, задан в секундах. |
scope |
Области, для которых действителен access_token. |
refresh_token |
Новый токен обновления OAuth 2.0. Вам следует заменить старый маркер обновления вновь полученным, чтобы обеспечить максимальный срок действия маркеров обновления. Примечание. Предоставляется, только если подан запрос на область offline_access. |
id_token |
Неподписанный JSON Web Token. Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или обеспечения безопасности. Дополнительные сведения о id_token см. в статье Маркеры идентификаторов платформы удостоверений Майкрософт. Примечание. Предоставляется, только если подан запрос на область openid. |
Предупреждение
Не пытайтесь проверять или читать токены для любого API, который вам не принадлежит, включая токены в этом примере, внутри вашего кода. Маркеры для служб Майкрософт могут использовать специальный формат, который не будет проверяться на соответствие JWT, и также могут быть зашифрованы для пользователей учетной записи Microsoft. Несмотря на то, что чтение маркеров является полезным средством отладки и обучения, не задавайте зависимости от него в коде или не опирайтесь на конкретные сведения о токенах, которые не предназначены для контролируемого вами API.
Отклик в случае ошибки
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, специфичных для STS, которые могут помочь при диагностике. |
timestamp |
Время возникновения ошибки. |
trace_id |
Уникальный идентификатор для запроса, который может помочь при диагностике. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Описание кодов ошибок и рекомендуемых действий в клиенте см. в разделе Коды ошибок конечных точек токенов.
Следующие шаги
- Перейдите на страницу примеров MSAL JS, чтобы приступить к созданию кода.
- Узнайте о сценариях обмена токенами.