Поток кода авторизации для платформы Microsoft Identity и OAuth 2,0Microsoft identity platform and OAuth 2.0 authorization code flow

Код авторизации OAuth 2.0 может использоваться в приложениях, установленных на устройстве, для получения доступа к защищенным ресурсам, таким как веб-API.The OAuth 2.0 authorization code grant can be used in apps that are installed on a device to gain access to protected resources, such as web APIs. Используя реализацию OAuth 2,0 на платформе Microsoft Identity, вы можете добавить доступ для входа и API для мобильных и классических приложений.Using the Microsoft identity platform implementation of OAuth 2.0, you can add sign in and API access to your mobile and desktop apps. Для выполнения задач этого руководства не предусмотрено использование конкретного языка. Здесь объясняется, как отправлять и получать сообщения HTTP без применения библиотек аутентификации Azure с открытым кодом.This guide is language-independent, and describes how to send and receive HTTP messages without using any of the Azure open-source authentication libraries.

В этой статье описывается, как программировать непосредственно по протоколу в приложении.This article describes how to program directly against the protocol in your application. По возможности рекомендуется использовать поддерживаемые библиотеки проверки подлинности Майкрософт (MSAL) вместо получения маркеров и вызова защищенных веб-API.When possible, we recommend you use the supported Microsoft Authentication Libraries (MSAL) instead to acquire tokens and call secured web APIs. Также ознакомьтесь с примерами приложений, которые используют MSAL.Also take a look at the sample apps that use MSAL.

Примечание

Не все Azure Active Directory сценарии, & функции поддерживаются конечной точкой платформы Microsoft Identity.Not all Azure Active Directory scenarios & features are supported by the Microsoft identity platform endpoint. Чтобы определить, следует ли использовать конечную точку платформы идентификации Майкрософт, ознакомьтесь с ограничениями платформы удостоверений Майкрософт.To determine if you should use the Microsoft identity platform endpoint, read about Microsoft identity platform limitations.

Описание потока кода авторизации OAuth 2.0 см. в разделе 4.1 спецификации OAuth 2.0.The OAuth 2.0 authorization code flow is described in section 4.1 of the OAuth 2.0 specification. Он используется для проверки подлинности и авторизации в большинстве типов приложений, включая веб-приложения и изначально установленные приложения.It's used to perform authentication and authorization in the majority of app types, including web apps and natively installed apps. Поток позволяет приложениям безопасно получать access_tokens, которые можно использовать для доступа к ресурсам, защищенным конечной точкой платформы Microsoft Identity.The flow enables apps to securely acquire access_tokens that can be used to access resources secured by the Microsoft identity platform endpoint.

Схема протоколаProtocol diagram

В общих чертах весь поток проверки подлинности для собственных или мобильных приложений можно представить следующим образом:At a high level, the entire authentication flow for a native/mobile application looks a bit like this:

Поток кода проверки подлинности OAuth

Запрос кода авторизацииRequest an authorization code

Поток кода авторизации начинается с того, что клиент направляет пользователя к конечной точке /authorize .The authorization code flow begins with the client directing the user to the /authorize endpoint. В этом запросе клиент запрашивает openid, offline_accessи https://graph.microsoft.com/mail.readразрешения от пользователя.In this request, the client requests the openid, offline_access, and https://graph.microsoft.com/mail.readpermissions from from the user. Некоторые разрешения ограничены администратором, например запись данных в каталог организации с помощью Directory.ReadWrite.All.Some permissions are admin-restricted, for example writing data to an organization's directory by using Directory.ReadWrite.All. Если приложение запрашивает доступ к одному из этих разрешений от пользователя организации, то пользователь получает сообщение об ошибке, сообщающее, что у него нет прав на согласие с разрешениями вашего приложения.If your application requests access to one of these permissions from an organizational user, the user receives an error message that says they're not authorized to consent to your app's permissions. Чтобы запросить доступ к областям, ограниченным администратором, необходимо запросить их непосредственно у администратора компании.To request access to admin-restricted scopes, you should request them directly from a company administrator. Дополнительные сведения см. в статье разрешения, ограниченные администратором.For more information, read Admin-restricted permissions.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345

Совет

Чтобы выполнить этот запрос, щелкните ссылку ниже!Click the link below to execute this request! После входа браузер будет перенаправлен по адресу https://localhost/myapp/, при этом в адресной строке будет указано code.After signing in, your browser should be redirected to https://localhost/myapp/ with a code in the address bar. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...;https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

ПараметрParameter Обязательный/необязательныйRequired/optional DescriptionDescription
tenant обязательноrequired Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение.The {tenant} value in the path of the request can be used to control who can sign into the application. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента.The allowed values are common, organizations, consumers, and tenant identifiers. Дополнительные сведения см. в описании протоколов.For more detail, see protocol basics.
client_id обязательноrequired Идентификатор приложения (клиента) , который портал Azure — регистрация приложений , назначенный приложению.The Application (client) ID that the Azure portal – App registrations experience assigned to your app.
response_type обязательноrequired Должен содержать code для потока кода авторизации.Must include code for the authorization code flow.
redirect_uri обязательноrequired URI перенаправления приложения, на который можно отправлять ответы проверки подлинности для их получения приложением.The redirect_uri of your app, where authentication responses can be sent and received by your app. Он должен в точности соответствовать одному из URI перенаправления, зарегистрированных на портале, но иметь форму закодированного URL-адреса.It must exactly match one of the redirect_uris you registered in the portal, except it must be url encoded. Для собственных и мобильных приложений следует использовать значение https://login.microsoftonline.com/common/oauth2/nativeclient по умолчанию.For native & mobile apps, you should use the default value of https://login.microsoftonline.com/common/oauth2/nativeclient.
scope обязательноrequired Разделенный пробелами список областей , для которого необходимо согласие пользователя.A space-separated list of scopes that you want the user to consent to. Для /authorize части запроса это может охватывать несколько ресурсов, позволяя приложению получить согласие на несколько веб-интерфейсов API, которые требуется вызвать.For the /authorize leg of the request, this can cover multiple resources, allowing your app to get consent for multiple web APIs you want to call.
response_mode рекомендуетсяrecommended Указывает метод, с помощью которого результирующий маркер будет отправлен приложению.Specifies the method that should be used to send the resulting token back to your app. Может применяться один из перечисленных ниже типов.Can be one of the following:

- query
- fragment
- form_post

query предоставляет код в качестве параметра строки запроса в URI перенаправления.query provides the code as a query string parameter on your redirect URI. Если вы запрашиваете маркер идентификатора с помощью неявного потока, вы не сможете использовать query, как указано в спецификации OpenID Connect. Если вы запрашиваете только код, то можете использовать query, fragmentили form_post.If you're requesting an ID token using the implicit flow, you can't use query as specified in the OpenID spec. If you're requesting just the code, you can use query, fragment, or form_post. form_post выполняет запрос POST, который содержит код для URI перенаправления.form_post executes a POST containing the code to your redirect URI. Дополнительные сведения см. в статье о протоколе OpenID Connect.For more info, see OpenID Connect protocol.
state рекомендуетсяrecommended Значение, включенное в запрос, которое также возвращается в ответе маркера.A value included in the request that will also be returned in the token response. Это может быть строка любого контента.It can be a string of any content that you wish. Как правило, для предотвращения подделки межсайтовых запросовиспользуется генерируемое случайным образом уникальное значение.A randomly generated unique value is typically used for preventing cross-site request forgery attacks. Также в этом значении кодируются сведения о состоянии пользователя в приложении перед выполнением запроса на аутентификацию. Например, это могут быть сведения об открытой на тот момент странице или представлении.The value can also encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
prompt необязательныйoptional Указывает требуемый тип взаимодействия с пользователем.Indicates the type of user interaction that is required. На текущий момент единственные допустимые значения — login, none и consent.The only valid values at this time are login, none, and consent.

При значении - prompt=login пользователю придется вводить учетные данные по запросу. Единый вход не сработает.- prompt=login will force the user to enter their credentials on that request, negating single-sign on.
- prompt=none является обратной. Это гарантирует, что пользователь не будет представлен ни в каких интерактивных запросах.- prompt=none is the opposite - it will ensure that the user isn't presented with any interactive prompt whatsoever. Если запрос не может быть выполнен автоматически с помощью единого входа, конечная точка платформы Microsoft Identity возвратит ошибку interaction_required.If the request can't be completed silently via single-sign on, the Microsoft identity platform endpoint will return an interaction_required error.
Если установить значение - prompt=consent, то после входа пользователь увидит диалоговое окно согласия OAuth с запросом на предоставление разрешений приложению.- prompt=consent will trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app.
- prompt=select_account приведет к прерыванию единого входа, предоставляющего возможность выбора учетной записи, в которой перечислены все учетные записи в сеансе или любой сохраненной учетной записи, или возможность использовать другую учетную запись в целом.- prompt=select_account will interrupt single sign-on providing account selection experience listing all the accounts either in session or any remembered account or an option to choose to use a different account altogether.
login_hint необязательныйoptional Можно применять для предварительного заполнения поля имени пользователя или адреса электронной почты на странице входа пользователя (если имя пользователя известно заранее).Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know their username ahead of time. Зачастую этот параметр используется в приложениях при повторной проверке подлинности. При этом имя пользователя извлекается во время предыдущего входа с помощью утверждения preferred_username.Often apps will use this parameter during re-authentication, having already extracted the username from a previous sign-in using the preferred_username claim.
domain_hint необязательныйoptional Может использоваться значение consumers или organizations.Can be one of consumers or organizations.

Если этот параметр включен, процесс обнаружения на основе электронной почты будет пропускаться на странице входа, что упрощает работу пользователя.If included, it will skip the email-based discovery process that user goes through on the sign-in page, leading to a slightly more streamlined user experience. Обычно этот параметр применяется в приложениях при повторной аутентификации. Для этого значение утверждения tid извлекается из предыдущего сеанса входа.Often apps will use this parameter during re-authentication, by extracting the tid from a previous sign-in. Если значение утверждения tid9188040d-6c67-4c5b-b112-36a304b66dad, следует использовать domain_hint=consumers.If the tid claim value is 9188040d-6c67-4c5b-b112-36a304b66dad, you should use domain_hint=consumers. Или используйте domain_hint=organizations.Otherwise, use domain_hint=organizations.
code_challenge_method необязательныйoptional Метод, используемый для кодирования code_verifier в параметре code_challenge.The method used to encode the code_verifier for the code_challenge parameter. Может использоваться одно из следующих значений:Can be one of the following values:

- plain
- S256

Если этот параметр не указан, для code_challenge принимается формат открытого текста, если задано значение code_challenge.If excluded, code_challenge is assumed to be plaintext if code_challenge is included. Платформа Microsoft Identity поддерживает как plain, так и S256.Microsoft identity platform supports both plain and S256. Дополнительные сведения см. в описании PKCE RFC.For more information, see the PKCE RFC.
code_challenge необязательныйoptional Используется, чтобы защитить разрешения кода авторизации из собственного клиента при помощи ключа проверки для обмена кодом (PKCE).Used to secure authorization code grants via Proof Key for Code Exchange (PKCE) from a native client. Является обязательным, если указан параметр code_challenge_method.Required if code_challenge_method is included. Дополнительные сведения см. в описании PKCE RFC.For more information, see the PKCE RFC.

На текущем этапе пользователю придется ввести учетные данные и завершить проверку подлинности.At this point, the user will be asked to enter their credentials and complete the authentication. Конечная точка платформы идентификации Майкрософт также обеспечит, чтобы пользователь предоставил разрешения, указанные в параметре запроса scope.The Microsoft identity platform endpoint will also ensure that the user has consented to the permissions indicated in the scope query parameter. Если пользователь не предоставил какие-либо из этих разрешений, конечная точка запросит их у пользователя.If the user has not consented to any of those permissions, it will ask the user to consent to the required permissions. Подробные сведения о разрешениях, согласии на предоставление и мультитенантных приложениях можно найти здесь.Details of permissions, consent, and multi-tenant apps are provided here.

После того как пользователь пройдет проверку подлинности и предоставит согласие, конечная точка платформы Microsoft Identity возвратит ответ в приложение на указанном redirect_uriс помощью метода, указанного в параметре response_mode.Once the user authenticates and grants consent, the Microsoft identity platform endpoint will return a response to your app at the indicated redirect_uri, using the method specified in the response_mode parameter.

Успешный ответSuccessful response

Успешный ответ с использованием метода response_mode=query выглядит следующим образом:A successful response using response_mode=query looks like:

GET https://login.microsoftonline.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
ПараметрParameter DescriptionDescription
code Запрашиваемый приложением код авторизации.The authorization_code that the app requested. Приложение может использовать код авторизации для запроса маркера доступа для целевого ресурса.The app can use the authorization code to request an access token for the target resource. Authorization_codes кратковременно, обычно срок их действия истекает через 10 минут.Authorization_codes are short lived, typically they expire after about 10 minutes.
state Если запрос содержит параметр "state", в ответе должно отображаться то же значение.If a state parameter is included in the request, the same value should appear in the response. Приложение должно проверить, совпадают ли значения параметра "state" в запросе и ответе.The app should verify that the state values in the request and response are identical.

Сообщение об ошибкеError response

Сообщения об ошибках также можно отправлять на redirect_uri , чтобы приложение обрабатывало их должным образом:Error responses may also be sent to the redirect_uri so the app can handle them appropriately:

GET https://login.microsoftonline.com/common/oauth2/nativeclient?
error=access_denied
&error_description=the+user+canceled+the+authentication
ПараметрParameter DescriptionDescription
error Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на них.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности.A specific error message that can help a developer identify the root cause of an authentication error.

Коды ошибок конечной точки авторизацииError codes for authorization endpoint errors

В таблице ниже описаны различные коды ошибок, которые могут возвращаться в параметре error ответа с ошибкой.The following table describes the various error codes that can be returned in the error parameter of the error response.

Код ошибкиError Code DescriptionDescription Действие клиентаClient Action
invalid_request Ошибка протокола, например отсутствует обязательный параметр.Protocol error, such as a missing required parameter. Исправьте запрос и отправьте его повторно.Fix and resubmit the request. Это ошибка разработки, которая обычно определяется во время первоначального тестирования.This is a development error typically caught during initial testing.
unauthorized_client Клиентскому приложению не разрешено запрашивать код авторизации.The client application isn't permitted to request an authorization code. Эта ошибка обычно возникает, когда клиентское приложение не зарегистрировано в Azure AD или не Добавлено в клиент Azure AD пользователя.This error usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. Приложение может отобразить пользователю запрос с инструкцией по установке приложения и его добавлению в Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
access_denied Владелец ресурса отказал в использованииResource owner denied consent Клиентское приложение может уведомить пользователя о том, что оно не может быть продолжено, пока пользователь не отправит.The client application can notify the user that it can't proceed unless the user consents.
unsupported_response_type Сервер авторизации не поддерживает тип ответа в запросе.The authorization server does not support the response type in the request. Исправьте запрос и отправьте его повторно.Fix and resubmit the request. Это ошибка разработки, которая обычно определяется во время первоначального тестирования.This is a development error typically caught during initial testing.
server_error Сервер обнаружил непредвиденную ошибку.The server encountered an unexpected error. Повторите запрос.Retry the request. Эти ошибки могут возникать в связи с временными условиями.These errors can result from temporary conditions. Из клиентского приложения может поступить сообщение о том, что его ответ задерживается из-за временной ошибки.The client application might explain to the user that its response is delayed to a temporary error.
temporarily_unavailable Сервер временно занят и не может обработать запрос.The server is temporarily too busy to handle the request. Повторите запрос.Retry the request. Клиентское приложение может объяснить пользователю, что его ответ откладывается из-за временного состояния.The client application might explain to the user that its response is delayed because of a temporary condition.
invalid_resource Целевой ресурс недопустим, так как он не существует, Azure AD не может найти его или неправильно настроен.The target resource is invalid because it does not exist, Azure AD can't find it, or it's not correctly configured. Это означает, что ресурс не существует или не настроен в клиенте.This error indicates the resource, if it exists, has not been configured in the tenant. Приложение может отобразить пользователю запрос с инструкцией по установке приложения и его добавлению в Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
login_required Слишком много пользователей или пользователи не найденыToo many or no users found Клиент запросил автоматическую аутентификацию (prompt=none), но одного пользователя не удалось найти.The client requested silent authentication (prompt=none), but a single user could not found. Это может означать, что в сеансе активно несколько пользователей или пользователи отсутствуют.This may mean there are multiple users active in the session, or no users. При этом учитывается выбранный клиент (например, если имеются две учетные записи Azure AD и один учетная запись Майкрософт, а consumers выбрана, автоматическая проверка подлинности будет работать).This takes into account the tenant chosen (for example, if there are two Azure AD accounts active and one Microsoft account, and consumers is chosen, silent authentication will work).
interaction_required Для запроса требуется взаимодействие с пользователем.The request requires user interaction. Требуется дополнительный шаг аутентификации или предоставление согласия.An additional authentication step or consent is required. Повторите запрос без prompt=none.Retry the request without prompt=none.

Запрос маркера доступаRequest an access token

После получения кода авторизации и разрешения от пользователя вы можете применить code для получения access_token к требуемому ресурсу.Now that you've acquired an authorization_code and have been granted permission by the user, you can redeem the code for an access_token to the desired resource. Для этого отправьте запрос POST к конечной точке /token:Do this by sending a POST request to the /token endpoint:

// 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=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.

Совет

Попытайтесь выполнить этот запрос в Postman.Try executing this request in Postman! (Не забудьте заменить code) попытаться выполнить этот запрос в Post(Don't forget to replace the code) Try running this request in Postman

ПараметрParameter Обязательный/необязательныйRequired/optional DescriptionDescription
tenant обязательноrequired Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение.The {tenant} value in the path of the request can be used to control who can sign into the application. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента.The allowed values are common, organizations, consumers, and tenant identifiers. Дополнительные сведения см. в описании протоколов.For more detail, see protocol basics.
client_id обязательноrequired Идентификатор приложения (клиента), которому в приложении назначена страница портал Azure – регистрация приложений .The Application (client) ID that the Azure portal – App registrations page assigned to your app.
grant_type обязательноrequired Должен быть authorization_code для потока кода авторизации.Must be authorization_code for the authorization code flow.
scope обязательноrequired Список областей с разделителями-пробелами.A space-separated list of scopes. Области, запрашиваемые на этом участке, должны быть эквивалентны областям, запрашиваемым на первом участке, или являться их подмножеством.The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the first leg. Все области должны быть из одного ресурса, а также с областями OIDC (profile, openid, email).The scopes must all be from a single resource, along with OIDC scopes (profile, openid, email). Более подробное описание областей можно найти в разделе, посвященном разрешениям, согласию на их предоставление и областям.For a more detailed explanation of scopes, refer to permissions, consent, and scopes.
code обязательноrequired Код авторизации, полученный на первом участке потока.The authorization_code that you acquired in the first leg of the flow.
redirect_uri обязательноrequired Значение redirect_uri, которое использовалось для получения кода authorization_code.The same redirect_uri value that was used to acquire the authorization_code.
client_secret необходим для веб-приложенийrequired for web apps Секрет приложения, созданный на портале регистрации для приложения.The application secret that you created in the app registration portal for your app. Не следует использовать секрет приложения в собственном приложении, так как client_secrets не могут быть надежно сохранены на устройствах.You shouldn't use the application secret in a native app because client_secrets can't be reliably stored on devices. Он необходим для веб-приложений и веб-API, которые позволяют безопасно хранить client_secret на стороне сервера.It's required for web apps and web APIs, which have the ability to store the client_secret securely on the server side. Секрет клиента должен быть преобразован в формат URL-адреса перед отправкой.The client secret must be URL-encoded before being sent. Для получения дополнительных сведений щелкните здесь.For more information click here.
code_verifier необязательныйoptional Это тот же параметр code_verifier, который использовался для получения кода авторизации (authorization_code).The same code_verifier that was used to obtain the authorization_code. Является обязательным, если в запросе на код авторизации использовался PKCE.Required if PKCE was used in the authorization code grant request. Дополнительные сведения см. в описании PKCE RFC.For more information, see the PKCE RFC.

Успешный ответSuccessful response

Успешный ответ маркера выглядит следующим образом:A successful token response will look like:

{
    "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...",
}
ПараметрParameter DescriptionDescription
access_token Запрашиваемый маркер доступа.The requested access token. Приложение может использовать этот маркер для аутентификации в защищенном ресурсе, таком как веб-API.The app can use this token to authenticate to the secured resource, such as a web API.
token_type Указывает значение типа маркера.Indicates the token type value. Единственный тип, поддерживаемый Azure AD, — носительThe only type that Azure AD supports is Bearer
expires_in Срок действия маркера доступа (в секундах).How long the access token is valid (in seconds).
scope Области, для которых действителен маркер доступа.The scopes that the access_token is valid for.
refresh_token Маркер обновления OAuth 2.0.An OAuth 2.0 refresh token. Приложение может использовать этот маркер для получения дополнительных маркеров доступа после истечения срока действия текущего маркера доступа.The app can use this token acquire additional access tokens after the current access token expires. Токены обновления действуют в течение долгого времени. Их можно использовать для длительного сохранения доступа к ресурсам.Refresh_tokens are long-lived, and can be used to retain access to resources for extended periods of time. См. дополнительные сведения об обновлении маркеров доступа.For more detail on refreshing an access token, refer to the section below.
Примечание. Предоставляется, только если подан запрос на область offline_access.Note: Only provided if offline_access scope was requested.
id_token A JSON Web Token (JWT).A JSON Web Token (JWT). Приложение может декодировать сегменты этого токена, чтобы запрашивать сведения о пользователе, выполнившем вход.The app can decode the segments of this token to request information about the user who signed in. Приложение может кэшировать и отображать значения, но оно не должно полагаться на них при авторизации или в целях безопасности.The app can cache the values and display them, but it should not rely on them for any authorization or security boundaries. См. дополнительные сведения о маркерах id_token: id_token reference.For more information about id_tokens, see the id_token reference.
Примечание. Предоставляется, только если подан запрос на область openid.Note: Only provided if openid scope was requested.

Сообщение об ошибкеError response

Сообщения об ошибках выглядят следующим образом:Error responses will look like:

{
  "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"
}
ПараметрParameter DescriptionDescription
error Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на них.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности.A specific error message that can help a developer identify the root cause of an authentication error.
error_codes Список кодов ошибок, характерных для службы маркеров безопасности, которые могут помочь при диагностике.A list of STS-specific error codes that can help in diagnostics.
timestamp Время возникновения ошибки.The time at which the error occurred.
trace_id Уникальный идентификатор для запроса, который может помочь при диагностике.A unique identifier for the request that can help in diagnostics.
correlation_id Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов.A unique identifier for the request that can help in diagnostics across components.

Коды ошибок конечных точек токеновError codes for token endpoint errors

Код ошибкиError Code DescriptionDescription Действие клиентаClient Action
invalid_request Ошибка протокола, например отсутствует обязательный параметр.Protocol error, such as a missing required parameter. Исправьте запрос и отправьте его повторно.Fix and resubmit the request
invalid_grant Недопустимый или устаревший код авторизации или средство проверки PKCE.The authorization code or PKCE code verifier is invalid or has expired. Повторите запрос к конечной точке /authorize и убедитесь, что параметр code_verifier указан правильно.Try a new request to the /authorize endpoint and verify that the code_verifier parameter was correct.
unauthorized_client Прошедший проверку подлинности клиент не авторизован для использования этого типа предоставления авторизации.The authenticated client isn't authorized to use this authorization grant type. Обычно это происходит, когда клиентское приложение не зарегистрировано в Azure AD или не добавляется в клиент Azure AD пользователя.This usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. Приложение может отобразить пользователю запрос с инструкцией по установке приложения и его добавлению в Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
invalid_client Сбой проверки подлинности клиента.Client authentication failed. Учетные данные клиента недействительны.The client credentials aren't valid. Чтобы устранить проблему, администратору приложения необходимо обновить учетные данные.To fix, the application administrator updates the credentials.
unsupported_grant_type Сервер авторизации не поддерживает тип предоставления авторизации.The authorization server does not support the authorization grant type. Измените тип предоставления в запросе.Change the grant type in the request. Ошибка этого типа должна происходить только во время разработки, и ее должны обнаружить при первоначальном тестировании.This type of error should occur only during development and be detected during initial testing.
invalid_resource Целевой ресурс недопустим, так как он не существует, Azure AD не может найти его или неправильно настроен.The target resource is invalid because it does not exist, Azure AD can't find it, or it's not correctly configured. Это означает, что ресурс, если он существует, не настроен в клиенте.This indicates the resource, if it exists, has not been configured in the tenant. Приложение может отобразить пользователю запрос с инструкцией по установке приложения и его добавлению в Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
interaction_required Для запроса требуется взаимодействие с пользователем.The request requires user interaction. К примеру, требуется дополнительный шаг проверки подлинности.For example, an additional authentication step is required. Выполните запрос снова, используя тот же ресурс.Retry the request with the same resource.
temporarily_unavailable Сервер временно занят и не может обработать запрос.The server is temporarily too busy to handle the request. Повторите запрос.Retry the request. Клиентское приложение может объяснить пользователю, что его ответ откладывается из-за временного состояния.The client application might explain to the user that its response is delayed because of a temporary condition.

Использование маркера доступаUse the access token

Успешно получив access_token, вы можете использовать токен в запросах в веб-API путем включения его в заголовок Authorization:Now that you've successfully acquired an access_token, you can use the token in requests to Web APIs by including it in the Authorization header:

Совет

Выполните этот запрос в Postman.Execute this request in Postman! (Сначала замените заголовок Authorization) попытаться выполнить этот запрос в Post(Replace the Authorization header first) Try running this request in Postman

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Обновление маркера доступаRefresh the access token

Срок действия маркеров доступа весьма ограничен, поэтому их нужно обновлять после его истечения, чтобы продолжить пользоваться запросами.Access_tokens are short lived, and you must refresh them after they expire to continue accessing resources. Для этого можно отправить еще один запрос POST на конечную точку /token, прибегнув к refresh_token вместо code.You can do so by submitting another POST request to the /token endpoint, this time providing the refresh_token instead of the code. Маркеры обновления действуют для всех разрешений, на которые ваш клиент уже получил согласия, например, маркер обновления выданный по запросу для scope=mail.read может использоваться для запроса нового маркера доступа для scope=api://contoso.com/api/UseResource.Refresh tokens are valid for all permissions that your client has already received consent for - thus, a refresh token issued on a request for scope=mail.read can be used to request a new access token for scope=api://contoso.com/api/UseResource.

Для маркеров обновления не устанавливается определенное время существования.Refresh tokens do not have specified lifetimes. Обычно у маркеров обновления относительно продолжительное время существования.Typically, the lifetimes of refresh tokens are relatively long. Но в некоторых случаях маркер обновления оказывается устаревшим или отозванным или не имеет достаточных привилегий для требуемого действия.However, in some cases, refresh tokens expire, are revoked, or lack sufficient privileges for the desired action. Ваше приложение должно ожидать и правильно обрабатывать ошибки, возвращаемые конечной точкой выдачи маркера.Your application needs to expect and handle errors returned by the token issuance endpoint correctly.

Хотя маркеры обновления не отменяются при использовании для получения новых маркеров доступа, ожидается удаление старого маркера обновления.Although refresh tokens aren't revoked when used to acquire new access tokens, you are expected to discard the old refresh token. В спецификации OAuth 2,0 говорится: "сервер авторизации может выдать новый маркер обновления. в этом случае клиент должен удалить старый маркер обновления и заменить его новым маркером обновления.The OAuth 2.0 spec says: "The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. Сервер авторизации может отозвать старый маркер обновления после выпуска нового маркера обновления для клиента ".The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client."

// 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=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for web apps. This secret needs to be URL-Encoded

Совет

Попытайтесь выполнить этот запрос в Postman.Try executing this request in Postman! (Не забудьте заменить refresh_token) попытаться выполнить этот запрос в Post(Don't forget to replace the refresh_token) Try running this request in Postman

ПараметрParameter DescriptionDescription
tenant обязательноrequired Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение.The {tenant} value in the path of the request can be used to control who can sign into the application. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента.The allowed values are common, organizations, consumers, and tenant identifiers. Дополнительные сведения см. в описании протоколов.For more detail, see protocol basics.
client_id обязательноrequired Идентификатор приложения (клиента) , который портал Azure — регистрация приложений , назначенный приложению.The Application (client) ID that the Azure portal – App registrations experience assigned to your app.
grant_type обязательноrequired Должен быть refresh_token для этого участка потока кода авторизации.Must be refresh_token for this leg of the authorization code flow.
scope обязательноrequired Список областей с разделителями-пробелами.A space-separated list of scopes. Области, запрашиваемые на этом участке, должны быть эквивалентны областям, запрашиваемым на исходном участке запроса кода авторизации, или являться их подмножеством.The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the original authorization_code request leg. Если области, указанные в этом запросе, охватывают несколько серверов ресурсов, конечная точка платформы Microsoft Identity возвратит маркер для ресурса, указанного в первой области.If the scopes specified in this request span multiple resource server, then the Microsoft identity platform endpoint will return a token for the resource specified in the first scope. Более подробное описание областей можно найти в разделе, посвященном разрешениям, согласию на их предоставление и областям.For a more detailed explanation of scopes, refer to permissions, consent, and scopes.
refresh_token обязательноrequired Токен обновления, полученный на втором участке потока.The refresh_token that you acquired in the second leg of the flow.
client_secret необходим для веб-приложенийrequired for web apps Секрет приложения, созданный на портале регистрации для приложения.The application secret that you created in the app registration portal for your app. Его не следует использовать в собственном приложении, так как client_secrets нельзя надежно хранить на устройствах.It should not be used in a native app, because client_secrets can't be reliably stored on devices. Он необходим для веб-приложений и веб-API, которые позволяют безопасно хранить client_secret на стороне сервера.It's required for web apps and web APIs, which have the ability to store the client_secret securely on the server side. Этот секрет должен быть закодирован в виде URL-адреса. Дополнительные сведения см. здесь.This secret needs to be URL-Encoded, for more information click here.

Успешный ответSuccessful response

Успешный ответ маркера выглядит следующим образом:A successful token response will look like:

{
    "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...",
}
ПараметрParameter DescriptionDescription
access_token Запрашиваемый маркер доступа.The requested access token. Приложение может использовать этот маркер для аутентификации в защищенном ресурсе, таком как веб-API.The app can use this token to authenticate to the secured resource, such as a web API.
token_type Указывает значение типа маркера.Indicates the token type value. Единственный тип, поддерживаемый Azure AD, — носительThe only type that Azure AD supports is Bearer
expires_in Срок действия маркера доступа (в секундах).How long the access token is valid (in seconds).
scope Области, для которых действителен маркер доступа.The scopes that the access_token is valid for.
refresh_token Новый токен обновления OAuth 2.0.A new OAuth 2.0 refresh token. Вам следует заменить старый токен обновления вновь полученным, чтобы обеспечить максимальный срок действия токенов обновления.You should replace the old refresh token with this newly acquired refresh token to ensure your refresh tokens remain valid for as long as possible.
Примечание. Предоставляется, только если подан запрос на область offline_access.Note: Only provided if offline_access scope was requested.
id_token Неподписанный веб-маркер JSON (JWT).An unsigned JSON Web Token (JWT). Приложение может декодировать сегменты этого токена, чтобы запрашивать сведения о пользователе, выполнившем вход.The app can decode the segments of this token to request information about the user who signed in. Приложение может кэшировать и отображать значения, но оно не должно полагаться на них при авторизации или в целях безопасности.The app can cache the values and display them, but it should not rely on them for any authorization or security boundaries. См. дополнительные сведения о маркерах id_token: id_token reference.For more information about id_tokens, see the id_token reference.
Примечание. Предоставляется, только если подан запрос на область openid.Note: Only provided if openid scope was requested.

Сообщение об ошибкеError response

{
  "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"
}
ПараметрParameter DescriptionDescription
error Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на них.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности.A specific error message that can help a developer identify the root cause of an authentication error.
error_codes Список кодов ошибок, характерных для службы маркеров безопасности, которые могут помочь при диагностике.A list of STS-specific error codes that can help in diagnostics.
timestamp Время возникновения ошибки.The time at which the error occurred.
trace_id Уникальный идентификатор для запроса, который может помочь при диагностике.A unique identifier for the request that can help in diagnostics.
correlation_id Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов.A unique identifier for the request that can help in diagnostics across components.

Описание кодов ошибок и рекомендуемых действий в клиенте см. в разделе Коды ошибок конечных точек токенов.For a description of the error codes and the recommended client action, see Error codes for token endpoint errors.