Поток кода авторизации 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 перенаправления: задайте URItype spa перенаправления с помощью редактора манифеста приложения в Центре администрирования 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

На текущем этапе пользователю предлагается ввести учетные данные и завершить аутентификацию. Платформа удостоверений Майкрософт также проверяет, согласился ли пользователь предоставить разрешения, указанные в параметре запроса scope. Если пользователь не предоставил какие-либо из этих разрешений, конечная точка запрашивает их у пользователя. См. сведения о разрешениях и согласии для платформы удостоверений Майкрософт.

После того как пользователь пройдет проверку подлинности и предоставит разрешения, платформа удостоверений Майкрософт вернет приложению ответ на указанный redirect_uri с помощью метода, указанного в параметре response_mode.

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

В этом примере показан успешный ответ с помощью response_mode=query:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

Вы также можете получить маркер идентификатора, если вы запрашиваете один из них, а в регистрации приложения включено неявное предоставление разрешения. Такое поведение иногда называют гибридным потоком. Он используется такими платформами, как ASP.NET.

Отклик в случае ошибки

Сообщения об ошибках также можно отправлять на redirect_uri , чтобы приложение обрабатывало их должным образом:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication

Коды ошибок конечной точки авторизации

В таблице ниже описаны различные коды ошибок, которые могут возвращаться в параметре error ответа с ошибкой.

Запрос маркера идентификатора или гибридного потока

Чтобы узнать, кем является пользователь, прежде чем активировать код авторизации, приложение зачастую также запрашивает маркер идентификатора при запросе кода авторизации. Этот подход называется гибридным потоком, так как он смешивает 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

Использование fragment в качестве режима реагирования вызывает проблемы для веб-приложений, считывающих код из перенаправления. Браузеры не передают фрагмент на веб-сервер. В таких ситуациях приложения должны использовать режим ответа form_post, чтобы обеспечить отправку всех данных на сервер.

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

В этом примере показан успешный ответ с помощью response_mode=fragment:

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345

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

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

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

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

// 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

Обратите внимание на то, что параметры являются такими же, как и при использовании запроса с помощью общего секрета, за исключением параметра 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..."
}

Отклик в случае ошибки

Этот пример представляет собой сообщение об ошибке:

{
  "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"
}

Коды ошибок конечных точек токенов

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

Теперь, когда вы успешно приобрели 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 говорит: "Сервер авторизации может выдавать новый маркер обновления, в этом случае клиент должен отменить старый маркер обновления и заменить его новым маркером обновления. Сервер авторизации может отозвать старый маркер обновления после выпуска нового маркера обновления для клиента".

// 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

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

Ниже приведен пример успешного ответа маркера:

{
    "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..."
}

Отклик в случае ошибки

{
  "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"
}

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

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

• Перейдите на страницу примеров MSAL JS, чтобы приступить к созданию кода.
• Сведения о сценариях обмена маркерами.