Платформа удостоверений Майкрософт и поток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-адрес ответа с подстановочными знаками. Это связано с тем, что конфиденциальный клиент может определить клиента, который приобрел маркер доступа. Затем конфиденциальный клиент может использовать маркер доступа для получения нового маркера доступа для нижестоящего API.

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

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

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

Описанные ниже действия представляют собой поток OBO и описываются на следующей схеме.

1. Клиентское приложение выполняет запрос к API A с токеном A (с утверждением aud для API A).
2. API A аутентифицируется в конечной точке выдачи токенов платформы удостоверений Майкрософт и запрашивает токен для доступа к API B.
3. Конечная точка выдачи токена платформы удостоверений Microsoft проверяет учетные данные 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 областью https://graph.microsoft.com действия веб-API с сертификатом. Запрос подписан секретом клиента и выполняется конфиденциальным клиентом.

// 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 Unauthorized и с заголовком HTTP WWW-Authenticate, содержащим ошибку и вызов утверждения. Клиент должен проанализировать этот заголовок и получить новый маркер от издателя маркеров, предоставив вызов утверждений, если он существует. Клиенты не должны повторить попытку доступа к службе среднего уровня с помощью кэшированного маркера доступа.

{
    "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, полученные в процессе потока OAuth2.0 OBO

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

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

• token_type: носителя
• истекает через: 3296
• ext_expires_in: 0
• expires_on: 1529627844
• Ресурс: 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 Использование области