Поток кода авторизации 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
typespaперенаправления с помощью редактора манифеста приложения в Центре администрирования Microsoft Entra.
Тип перенаправления spa обратно совместим с неявным потоком. Приложения, в настоящее время использующие неявный поток для получения токенов, могут переноситься в spa тип URI перенаправления без проблем и продолжать использовать неявный поток. Несмотря на эту обратную совместимость, рекомендуется использовать поток кода проверки подлинности с PKCE для spAs.
Если вы попытаетесь использовать поток кода авторизации без настройки CORS для URI перенаправления, эта ошибка появится в консоли:
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/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
| Параметр | Обязательный/необязательный | Description |
|---|---|---|
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 |
рекомендованный/обязательный | Используется, чтобы защитить разрешения кода авторизации с помощью ключа проверки для обмена кодом (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 ответа с ошибкой.
| Код ошибки | Description | Действие клиента |
|---|---|---|
invalid_request |
Ошибка протокола, например отсутствует обязательный параметр. | Исправьте запрос и отправьте его повторно. Это ошибка разработки, которая обычно определяется во время первоначального тестирования. |
unauthorized_client |
Клиентскому приложению не разрешено запрашивать код авторизации. | Эта ошибка обычно возникает, когда клиентское приложение не зарегистрировано в идентификаторе Microsoft Entra или не добавляется в клиент Microsoft Entra пользователя. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в идентификатор Microsoft Entra. |
access_denied |
Владелец ресурса отказал в использовании | Клиентское приложение может уведомить пользователя, что для продолжения работы необходимо согласие пользователя. |
unsupported_response_type |
Сервер авторизации не поддерживает тип ответа в запросе. | Исправьте запрос и отправьте его повторно. Это ошибка разработки, которая обычно определяется во время первоначального тестирования. Если она отображается в гибридном потоке, это означает, что необходимо включить параметр неявного предоставления маркера идентификатора для регистрации клиентского приложения. |
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
| Обновленный параметр | Обязательный/необязательный | Description |
|---|---|---|
response_type |
обязательно | Добавив id_token, вы указываете серверу, что приложение должно иметь маркер идентификатора в ответе от конечной точки /authorize. |
scope |
обязательно | Для маркеров идентификаторов необходимо обновить этот параметр, чтобы включить области маркеров идентификаторов — openid и при необходимости profile и email. |
nonce |
обязательно | Значение, включенное в запрос и созданное приложением, которое входит в состав маркера id_token в качестве утверждения. Приложение может проверить это значение во избежание атак с использованием воспроизведения токена. Это значение обычно представляет собой случайную уникальную строку, которую можно использовать для определения источника запроса. |
response_mode |
рекомендуется | Указывает метод, с помощью которого результирующий маркер будет отправлен приложению. Значение по умолчанию — query это просто код авторизации, но fragment если запрос содержит указанный id_token response_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 в запросе и отклике идентичны. |
Активация кода для маркера доступа
Все конфиденциальные клиенты имеют возможность использовать секреты клиента или учетные данные сертификата. Симметричные общие секреты создаются платформой удостоверений Майкрософт. Учетные данные сертификата — это асимметричные ключи, отправленные разработчиком. Дополнительные сведения см. в статье Учетные данные сертификата проверки подлинности приложения платформы удостоверений Майкрософт.
Для обеспечения лучшей безопасности рекомендуется использовать учетные данные сертификата. Общедоступные клиенты, которые включают в себя собственные приложения и одностраничные приложения, не должны использовать секреты или сертификаты при активации кода авторизации. Всегда следите за тем, чтобы идентификаторы 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.
| Параметр | Обязательный/необязательный | Description |
|---|---|---|
tenant |
обязательно | Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента. Дополнительные сведения см. в разделе "Конечные точки". |
client_id |
обязательно | Идентификатор приложения (клиента), который центр администрирования Microsoft Entra — Регистрация приложений страницу, назначенную вашему приложению. |
scope |
необязательно | Список областей с разделителями-пробелами. Все области должны быть из одного ресурса, а также с областями OIDC (profile, openid, email). См. сведения о разрешениях и согласии для платформы удостоверений Майкрософт. Этот параметр является расширением Майкрософт для потока кода авторизации, предназначенное для того, чтобы разрешить приложениям объявлять ресурсы, для которых они хотят получить маркер во время активации маркера. |
code |
обязательно | Значение authorization_code, полученное в первой части потока. |
redirect_uri |
обязательно | То же значение redirect_uri, что использовалось для получения authorization_code. |
grant_type |
обязательно | Должен быть authorization_code для потока кода авторизации. |
code_verifier |
рекомендуется | Тот же code_verifier, который использовался для получения authorization_code. Является обязательным, если в запросе на код авторизации использовался 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
| Параметр | Обязательный/необязательный | Description |
|---|---|---|
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, который был использован для получения authorization_code. Является обязательным, если в запросе на код авторизации использовался PKCE. Дополнительные сведения см. в описании PKCE RFC. |
client_assertion_type |
обязательный для конфиденциальных веб-приложений | Для использования учетных данных сертификата необходимо задать значение urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion |
обязательный для конфиденциальных веб-приложений | Утверждение (JSON Web Token) которое необходимо создать и подписать с помощью сертификата, зарегистрированного как учетные данные для приложения. Ознакомьтесь с информацией об учетных данных сертификата, чтобы узнать, как зарегистрировать сертификат и задать формат утверждения. |
Обратите внимание на то, что параметры являются такими же, как и при использовании запроса с помощью общего секрета, за исключением параметра 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_token: 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 |
Список кодов ошибок, характерных для службы маркеров безопасности, которые могут помочь при диагностике. |
timestamp |
Время возникновения ошибки. |
trace_id |
Уникальный идентификатор для запроса, который может помочь при диагностике. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Коды ошибок конечных точек токенов
| Код ошибки | Description | Действие клиента |
|---|---|---|
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, или являться их подмножеством. Если области, указанные в этом запросе, охватывают несколько серверов ресурсов, платформа удостоверений Майкрософт вернет маркер ресурса, указанного в первой области. См. сведения о разрешениях и согласии для платформы удостоверений Майкрософт. |
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, является носитель. |
expires_in |
Срок действия маркера доступа (в секундах). |
scope |
Области, для которых действителен access_token. |
refresh_token |
Новый токен обновления OAuth 2.0. Вам следует заменить старый маркер обновления вновь полученным, чтобы обеспечить максимальный срок действия маркеров обновления. Примечание. Предоставляется, только если подан запрос на область offline_access. |
id_token |
Неподписанный JSON Web Token. Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или обеспечения безопасности. Дополнительные сведения о id_token см. в статье Маркеры идентификаторов платформы удостоверений Майкрософт. Примечание. Предоставляется, только если подан запрос на область openid. |
Предупреждение
Не пытайтесь проверить или прочесть маркеры для любого API, который вам не принадлежит, включая маркеры в этом примере, в коде. Маркеры для служб Майкрософт могут использовать специальный формат, который не будет проверяться как JWT и может также быть зашифрован для пользователей-потребителей (учетная запись Майкрософт). Несмотря на то, что чтение маркеров является полезным средством отладки и обучения, не задавайте зависимости от него в коде или не опирайтесь на конкретные сведения о токенах, которые не предназначены для контролируемого вами 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 |
Список кодов ошибок, характерных для службы маркеров безопасности, которые могут помочь при диагностике. |
timestamp |
Время возникновения ошибки. |
trace_id |
Уникальный идентификатор для запроса, который может помочь при диагностике. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Описание кодов ошибок и рекомендуемых действий в клиенте см. в разделе Коды ошибок конечных точек токенов.
Следующие шаги
- Перейдите на страницу примеров MSAL JS, чтобы приступить к созданию кода.
- Сведения о сценариях обмена маркерами.