Поток On-Behalf-Of в OAuth 2.0 и платформа удостоверений Майкрософт

Поток от имени (OBO) описывает сценарий веб-API, используя удостоверение, отличное от собственного для вызова другого веб-API. Называется делегированием в OAuth, намерение заключается в передаче удостоверения пользователя и разрешений через цепочку запросов.

Чтобы служба среднего уровня обеспечивала проверку подлинности запросов к нижестоящей службе, она должна защитить маркер доступа от платформа удостоверений Майкрософт. Он использует только делегированные область, а не роли приложения. Роли остаются присоединенными к субъекту (пользователю) и никогда не к приложению, работающему от имени пользователя. Это происходит, чтобы предотвратить получение пользователем разрешений на ресурсы, к которых у них не должно быть доступа.

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

Ограничения клиентов

Если субъект-служба запрашивал маркер только для приложений и отправлял его в API, то этот API обменивается маркером, который не представляет исходного субъекта-службы. Это связано с тем, что поток OBO работает только для субъектов-пользователей. Вместо этого он должен использовать поток учетных данных клиента для получения маркера только для приложений. В случае с одностраничными приложениями (SPAs) они должны передать маркер доступа в конфиденциальный клиент среднего уровня, чтобы выполнять потоки OBO.

Если клиент использует неявный поток для получения id_token и имеет дикие карта в URL-адресе ответа, id_token нельзя использовать для потока OBO. Дикий карта — это URL-адрес, который заканчивается символом*. Например, если https://myapp.com/* был URL-адрес ответа, id_token нельзя использовать, так как он недостаточно конкретный для идентификации клиента. Это позволит предотвратить выдачу маркера. Однако маркеры доступа, полученные через неявный поток предоставления, активируются конфиденциальным клиентом, даже если инициирующий клиент имеет дикий URL-адрес ответа карта зарегистрированный URL-адрес ответа. Это связано с тем, что конфиденциальный клиент может определить клиента, который приобрел маркер доступа. Затем конфиденциальный клиент может использовать маркер доступа для получения нового маркера доступа для нижестоящего API.

Кроме того, приложения с пользовательскими ключами подписывания не могут использоваться в качестве API среднего уровня в потоке OBO. Сюда входят корпоративные приложения, настроенные для единого входа. Если API среднего уровня использует пользовательский ключ подписи, подчиненный API не проверяет подпись маркера доступа, переданного в него. Это приводит к ошибке, так как маркеры, подписанные ключом, контролируемым клиентом, не могут быть безопасно приняты.

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

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

Последующие шаги образуют поток OBO. Эти шаги поясняются на следующей схеме.

1. Клиентское приложение отправляет запрос к API A с маркером A (с утверждением aud API А).
2. API A выполняет проверку подлинности на конечной точке выдачи маркера платформы удостоверений Майкрософт и запрашивает маркер доступа к API B.
3. Конечная точка выдачи маркера платформы удостоверений Майкрософт проверяет учетные данные API A и маркер A и выдает маркера доступа для API B (маркер B) к API A.
4. Маркер B задается API A в заголовке авторизации запроса к API B.
5. Данные из защищенного ресурса возвращаются API B в API A, а затем клиенту.

В этом сценарии служба среднего уровня получает согласие пользователя на доступ к API нижнего уровня без взаимодействия с пользователем. Поэтому при проверке подлинности параметр предоставления доступа к нижестоящему API предоставляется заранее в рамках шага согласия. Сведения о том, как реализовать это в приложении, см. в статье "Получение согласия" для приложения среднего уровня.

Запрос маркера доступа среднего уровня

Чтобы запросить маркер доступа, отправьте HTTP-запрос POST к конечной точке маркера платформы удостоверений Майкрософт для конкретного клиента с указанными ниже параметрами.

https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

Существуют два сценария. Их выбор зависит от типа защиты клиентского приложения — с помощью общего секрета или с помощью сертификата.

Первый сценарий: запрос маркера доступа с помощью общего секрета

При использовании общего секрета запрос маркера взаимного доступа между службами содержит следующие параметры:

Пример

Следующий HTTP-запрос POST запрашивает маркер и маркер обновления доступа с областью user.read для веб-API https://graph.microsoft.com. Запрос подписан секретом клиента и выполняется конфиденциальным клиентом.

//line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of

Второй сценарий: запрос маркера доступа с помощью сертификата

Запрос маркера доступа между службами с сертификатом содержит следующие параметры в дополнение к параметрам из предыдущего примера:

Обратите внимание, что параметры почти те же, что и в случае запроса по общему секрету, за исключением того, что client_secret параметр заменяется двумя параметрами: a client_assertion_type и client_assertion. Для client_assertion_type параметра задано urn:ietf:params:oauth:client-assertion-type:jwt-bearer значение, а client_assertion параметру присваивается маркер JWT, подписанный закрытым ключом сертификата.

Пример

Ниже приведен HTTP-запрос POST маркера доступа с областью user.read для веб-API https://graph.microsoft.com с сертификатом. Запрос подписан секретом клиента и выполняется конфиденциальным клиентом.

// line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access

Ответ на запрос маркера доступа среднего уровня

Если доступ предоставлен, ответ будет содержать JSON-файл OAuth 2.0 со следующими параметрами.

Пример ответа с успешным предоставлением доступа

В следующем примере показано сообщение о предоставлении доступа в ответ на запрос маркера доступа к веб-API https://graph.microsoft.com. Ответ содержит маркер доступа и маркер обновления и подписан закрытым ключом сертификата.

{
    "token_type": "Bearer",
    "scope": "https://graph.microsoft.com/user.read",
    "expires_in": 3269,
    "ext_expires_in": 0,
    "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
    "refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}

Этот маркер доступа — это маркер с форматированием версии 1.0 для Microsoft Graph. Версия обусловлена тем, что формат маркера основан на ресурсе, к которому осуществляется доступ, и не связан с конечными точками, используемыми для запроса. Microsoft Graph настроен для принятия маркеров версии 1.0, поэтому платформа удостоверений Майкрософт создает маркеры доступа версии 1.0, когда клиент запрашивает маркеры для Microsoft Graph. Другие приложения могут указывать на то, что они хотят маркеры формата версии 2.0, маркеры формата версии 1.0 или даже собственные или зашифрованные форматы маркеров. Конечные точки версии 1.0 и версии 2.0 могут выдавать любой формат маркера. Таким образом, ресурс всегда может получить правильный формат маркера независимо от того, как или где маркер запрашивается клиентом.

Пример ответа с сообщением об ошибке

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

Чтобы вернуть эту ошибку клиенту, служба среднего уровня отвечает с протоколом HTTP 401 Несанкционированно и с заголовком HTTP www-Authentication HTTP, содержащим ошибку и вызов утверждения. Клиент должен проанализировать этот заголовок и получить новый маркер от издателя маркеров, предоставив вызов утверждений, если он существует. Клиенты не должны повторить попытку доступа к службе среднего уровня с помощью кэшированного маркера доступа.

{
    "error":"interaction_required",
    "error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
    "error_codes":[50079],
    "timestamp":"2017-05-01 22:43:20Z",
    "trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
    "claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

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

Теперь служба среднего уровня может использовать маркер, полученный ранее, для выполнения аутентифицированных запросов к нижестоящему веб-API, задав маркер в заголовке Authorization .

Пример

    GET /v1.0/me HTTP/1.1
    Host: graph.microsoft.com
    Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

Утверждения SAML, полученные с помощью потока OBO в OAuth2.0

Некоторые веб-службы на основе OAuth должны получать доступ к другим API веб-служб, получающим утверждения SAML в неинтерактивных потоках. Идентификатор Microsoft Entra может предоставить утверждение SAML в ответ на поток On-Behalf-Of, использующий веб-службу на основе SAML в качестве целевого ресурса.

Это нестандартное расширение для потока OAuth 2.0 On-Behalf-Of, которое позволяет приложению на основе OAuth2 получать доступ к конечным точкам API веб-службы, использующего токены SAML.

Получение токена SAML при помощи запроса OBO с общим секретом

Запрос утверждения SAML между службами содержит следующие параметры:

Ответ содержит токен SAML, закодированный в UTF8 и Base 64url.

• SubjectConfirmationData для утверждения SAML, полученного из вызова OBO: если целевое приложение требует Recipient значения вSubjectConfirmationData, то значение должно быть настроено как первый неуверенный карта URL-адрес ответа в конфигурации приложения ресурсов. Так как URL-адрес ответа по умолчанию не используется для определения Recipient значения, может потребоваться изменить порядок URL-адресов ответа в конфигурации приложения, чтобы убедиться, что используется первый неупорядоченный URL-адрес ответа карта. Дополнительные сведения см. в разделе URL-адреса ответа.
• Узел SubjectConfirmationData: узел не может содержать InResponseTo атрибут, так как он не является частью ответа SAML. Приложение, получающее токен SAML, должно иметь возможность принимать утверждение SAML без атрибута InResponseTo .
• Разрешения API: необходимо добавить необходимые разрешения API в приложение среднего уровня, чтобы разрешить доступ к приложению SAML для запроса маркера для области действия /.default приложения SAML.
• Согласие. Согласие должно быть предоставлено для получения токена SAML, содержащего данные пользователя в потоке OAuth. Дополнительные сведения см. в разделе "Получение согласия" для приложения среднего уровня.

Отклик с утверждением SAML

• token_type: Bearer
• expires_in: 3296
• ext_expires_in: 0
• expires_on: 1529627844
• resource: https://api.contoso.com
• access_token: <утверждение SAML>
• issued_token_type: urn:ietf:params:oauth:token-type:saml2
• refresh_token: <маркер обновления>

Получение согласия для приложения среднего уровня

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

Область .default и объединенное согласие

Приложение среднего уровня добавляет клиент в список известных клиентских приложений (knownClientApplications) в своем манифесте. Если запрос согласия активируется клиентом, поток согласия предназначен как для себя, так и для приложения среднего уровня. На платформе удостоверений Майкрософт эта задача выполняется с помощью области .default. Область .default — это специальный область, который используется для запроса согласия на доступ ко всем область, для которым у приложения есть разрешения. Это полезно, если приложению требуется доступ к нескольким ресурсам, но пользователю нужно только один раз предоставить согласие.

При активации экрана согласия с помощью известных клиентских приложений и .defaultна экране согласия отображаются разрешения как для клиента, так и для API среднего уровня, а также запрашиваются разрешения, необходимые API среднего уровня. Пользователь дает согласие для обоих приложений, после чего выполняется поток OBO.

Определенная в запросе служба ресурсов (API) должна представлять собой API, для которого клиентское приложение запрашивает маркер доступа в ответ на вход пользователя. Например, scope=openid https://middle-tier-api.example.com/.default (чтобы запросить маркер доступа для API среднего уровня) или scope=openid offline_access .default (если ресурс не определен, по умолчанию используется Microsoft Graph).

Независимо от того, какой API определяется в запросе авторизации, запрос согласия объединяется со всеми необходимыми разрешениями, настроенными для клиентского приложения. Все необходимые разрешения, настроенные для каждого API среднего уровня, перечисленные в списке необходимых разрешений клиента, которые идентифицировали клиента как известное клиентское приложение, также включаются.

Предварительно настроенные приложения

Ресурс может указать, что у заданного приложения всегда есть разрешение на прием определенных областей. Это полезно, чтобы сделать подключения между интерфейсным клиентом и серверным ресурсом более простым. Ресурс может объявлять несколько предварительно несанкционированных приложений (preAuthorizedApplications) в манифесте. Любое такое приложение может запрашивать эти разрешения в потоке OBO и получать их без предоставления согласия пользователя.

Согласие администратора

Администратор клиента может обеспечить приложения разрешениями для вызова необходимых им API, предоставив согласие администратора для приложения среднего уровня. Для этого администратор может найти приложение среднего уровня в своем клиенте, открыть страницу необходимых разрешений и выбрать предоставляемые разрешения для приложения. Дополнительные сведения о согласии администратора доступны в документации о согласии и разрешениях.

Использование одного приложения

В некоторых сценариях можно использовать только одно связывание среднего уровня и внешнего клиента. В этом сценарии проще сделать это одним приложением, отрицая необходимость в приложении среднего уровня. Для аутентификации между внешним интерфейсом и веб-API можно использовать файлы cookie, маркер id_token или маркер доступа, запрошенный для приложения. Затем можно запросить согласие у этого приложения для доступа к внутреннему ресурсу.

См. также

Дополнительные сведения о протоколе OAuth 2.0 и другом способе проверки подлинности между службами с использованием учетных данных клиента.

• Предоставление учетных данных клиента OAuth 2.0 на платформе удостоверений Майкрософт
• Поток кода OAuth 2.0 на платформе удостоверений Майкрософт
• Использование области /.default