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

Тип предоставления кода авторизации OAuth 2.0 или поток кода авторизации позволяет клиентскому приложению получать авторизованный доступ к защищенным ресурсам, таким как веб-API. Для потока кода авторизации требуется пользовательский агент, который поддерживает перенаправление с сервера авторизации (платформа удостоверений Майкрософт) обратно в ваше приложение. Например, веб-браузер, классическое или мобильное приложение, управляемое пользователем для входа в ваше приложение и получения доступа к данным.

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

Приложения, поддерживающие поток кода авторизации

Используйте поток кода авторизации в сочетании с ключом проверки для обмена кодами (PKCE) и OpenID Connect (OIDC) для получения маркеров доступа и маркеров ИД в следующих типах приложений:

Сведения о протоколе

Описание потока кода авторизации OAuth 2.0 см. в разделе 4.1 спецификации OAuth 2.0. Приложения, использующие поток кода авторизации OAuth 2.0, получают access_token для включения в запросы к ресурсам, защищенным платформой удостоверений Майкрософт (обычно API). Приложения также могут запрашивать новые идентификаторы и маркеры доступа для ранее прошедших проверку подлинности сущностей с помощью механизма обновления.

На этой диаграмме показано высокоуровневое представление потока проверки подлинности:

Diagram shows OAuth authorization code flow. Native app and Web A P I interact by using tokens as described in this article.

URI перенаправления для одностраничных приложений (SPA)

URI перенаправления для SPA, которые используют поток кода авторизации, требуют специальной конфигурации.

  • Добавьте URI перенаправления, который поддерживает поток кода авторизации с PKCE и общий доступ к ресурсам независимо от источника (CORS): выполните инструкции из раздела URI перенаправления: MSAL.js 2.0 с потоком кода авторизации.
  • Обновление URI перенаправления: задайте URItypespa перенаправления с помощью редактора манифеста приложения в Центре администрирования Microsoft Entra.

Тип перенаправления spa обратно совместим с неявным потоком. Приложения, в настоящее время использующие неявный поток для получения токенов, могут переноситься в spa тип URI перенаправления без проблем и продолжать использовать неявный поток.

Если вы попытаетесь использовать поток кода авторизации без настройки 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 . В этом запросе клиент запрашивает у пользователя разрешения openid, offline_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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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 перенаправления, зарегистрированных на портале, но иметь форму закодированного 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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_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 в запросе и отклике идентичны.

Активация кода для маркера доступа

Все конфиденциальные клиенты имеют возможность использовать секреты клиента или учетные данные сертификата. Симметричные общие секреты создаются платформой удостоверений Майкрософт. Учетные данные сертификата — это асимметричные ключи, отправленные разработчиком. Дополнительные сведения см. в статье Учетные данные сертификата проверки подлинности приложения платформы удостоверений Майкрософт.

Для обеспечения лучшей безопасности рекомендуется использовать учетные данные сертификата. Общедоступные клиенты, которые включают в себя собственные приложения и одностраничные приложения, не должны использовать секреты или сертификаты при активации кода авторизации. Всегда следите за тем, чтобы идентификаторы 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=204196ef-b7fd-461f-89b7-f778e1568c41
&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.

Запрос маркера доступа с учетными данными сертификата

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
Параметр Описание
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 Сбой проверки подлинности клиента. Недопустимые учетные данные клиента. Чтобы устранить эту проблему, приложение Администратор istrator обновляет учетные данные.
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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
Параметр Описание
error Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки.
error_description Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности.
error_codes Список кодов ошибок, характерных для службы маркеров безопасности, которые могут помочь при диагностике.
timestamp Время возникновения ошибки.
trace_id Уникальный идентификатор для запроса, который может помочь при диагностике.
correlation_id Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов.

Описание кодов ошибок и рекомендуемых действий в клиенте см. в разделе Коды ошибок конечных точек токенов.

Следующие шаги