Microsoft 标识平台和 OAuth 2.0 代理流

代理 (OBO) 流描述了 Web API 使用其自身以外的标识来调用另一个 Web API 的方案。 在 OAuth 中称为委派，目的是通过请求链传递用户的标识和权限。

要使中间层服务向下游服务发出身份验证请求，该服务需要保护 Microsoft 标识平台提供的访问令牌。 它仅使用委派范围，而不使用应用程序角色。 角色仍然依附于主体（用户），而不依附于代表用户操作的应用程序。 这是为了防止用户获得他们无权访问的资源的权限。

本文介绍如何直接针对应用程序中的协议进行编程。 如果可能，建议改用受支持的Microsoft身份验证库（MSAL）来 获取令牌并调用受保护的 Web API。 另请参阅 使用 MSAL 的示例应用 。

如果服务主体请求仅限应用的令牌并将其发送到 API，则该 API 将交换不代表原始服务主体的令牌。 这是因为 OBO 流仅适用于用户主体。 相反，它必须使用 客户端凭据流 来获取仅限应用的令牌。 对于单页应用 (SPA)，应改为将访问令牌传递给中间层机密客户端，才能执行 OBO 流。

如果客户端使用隐式流来获取 id_token，且在回复 URL 中也具有通配符，id_token 就无法用于 OBO 流。 通配符是以 * 字符结尾的 URL。 例如，如果 https://myapp.com/* 是回复 URL，就无法使用 id_token，因为它不够具体，无法识别客户端。 这将阻止颁发令牌。 但是，通过隐式授予流获取的访问令牌由机密客户端兑换，即使发起的客户端已注册通配符回复 URL 也是如此。 这是因为机密客户端可以识别获取访问令牌的客户端。 然后，机密客户端可以使用访问令牌为下游 API 获取新的访问令牌。

此外，具有自定义签名密钥的应用程序不能用作 OBO 流中的中间层 API。 这包括为单一登录配置的企业应用程序。 如果中间层 API 使用自定义签名密钥，则下游 API 不会验证传递给它的访问令牌的签名。 这会导致错误，因为无法安全地接受使用客户端控制的密钥签名的令牌。

假定用户使用 OAuth 2.0 授权代码授予流 或其他登录流对应用程序进行身份验证。 此时，应用程序已获得 API A 的访问令牌（令牌 A），其中包含用户对访问中间层 Web API (API A) 的声明和许可。 现在，API A 需要向下游 Web API (API B) 发出经过身份验证的请求。

接下来的步骤构成了 OBO 流，并在下图中进行说明。

1. 客户端应用程序使用令牌 A（其中包含 API A 的 aud 声明）向 API A 发出请求。
2. API A 向 Microsoft 标识平台令牌颁发终结点进行身份验证并请求访问 API B 的令牌。
3. Microsoft 标识平台令牌颁发终结点使用令牌 A 验证 API A 的凭据，并颁发供 API B（令牌 B）访问 API A 的访问令牌。
4. 令牌 B 由 API A 在向 API B 发出的请求的 authorization 标头中设置。
5. 受保护资源中的数据将通过 API B 返回到 API A，然后返回到客户端。

在此方案中，中间层服务无需用户干预，即可获取用户对访问下游 API 的同意。 因此，在身份验证过程的许可步骤中会提前显示授权访问下游 API 的选项。 若要了解如何在应用中实现此功能，请参阅获得 中间层应用程序的同意。

若要请求访问令牌，请使用以下参数向特定于租户的 Microsoft 标识平台令牌终结点发出 HTTP POST。

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

有两种情况，具体取决于客户端应用程序选择由共享密钥还是由证书保护。

使用共享密钥时，服务到服务访问令牌请求包含以下参数：

以下 HTTP POST 通过 user.read 作用域请求 https://microsoftgraph.chinacloudapi.cn Web API 的访问令牌和刷新令牌。 请求使用客户端密码进行签名，并由机密客户端发出。

//line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.partner.microsoftonline.cn/<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://microsoftgraph.chinacloudapi.cn/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://microsoftgraph.chinacloudapi.cn Web API 的访问令牌。 请求使用客户端密码进行签名，并由机密客户端发出。

// line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.partner.microsoftonline.cn/<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://microsoftgraph.chinacloudapi.cn/user.read+offline_access

成功响应是具有以下参数的 JSON OAuth 2.0 响应。

以下示例演示对 https://microsoftgraph.chinacloudapi.cn Web API 的访问令牌请求的成功响应。 响应包含访问令牌和刷新令牌，并使用证书的私钥进行签名。

{
    "token_type": "Bearer",
    "scope": "https://microsoftgraph.chinacloudapi.cn/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}"
}

此访问令牌是 v1.0 格式的 Microsoft Graph 令牌。 这是因为令牌格式基于所访问的资源，而与请求它时使用的终结点无关。 Microsoft Graph 设置为接受 v1.0 令牌，因此当客户端请求 Microsoft Graph 的令牌时，Microsoft 标识平台会生成 v1.0 访问令牌。 其他应用可能指示他们希望 v2.0 格式令牌、v1.0 格式令牌，甚至专有或加密令牌格式。 v1.0 和 v2.0 终结点都可以发出任意一种令牌格式。 这样，无论客户端请求令牌的方式或位置，资源都可以始终获取正确的令牌格式。

如果下游 API 设置了条件访问策略（如 多重身份验证），则令牌终结点在尝试获取下游 API 的访问令牌时返回错误响应。 中间层服务应向客户端应用程序显示此错误，以便客户端应用程序可以提供用户交互，以满足条件访问策略。

若要 将此错误显示回 客户端，中间层服务会使用 HTTP 401 未授权答复，并具有包含错误和声明质询的 WWW-Authenticate 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\"]}}}"
}

现在，中间层服务可以通过在标头中 Authorization 设置令牌，使用之前获取的令牌向下游 Web API 发出经过身份验证的请求。

    GET /v1.0/me HTTP/1.1
    Host: microsoftgraph.chinacloudapi.cn
    Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

某些基于 OAuth 的 Web 服务需要访问在非交互式流中接受 SAML 断言的其他 Web 服务 API。 Microsoft Entra ID 可以提供 SAML 断言，以响应将基于 SAML 的 Web 服务用作目标资源的代理流。

这是 OAuth 2.0 On-Behalf-Of 流的非标准扩展，允许基于 OAuth2 的应用程序访问使用 SAML 令牌的 Web 服务 API 终结点。

服务到服务的请求中包含用于 SAML 断言的以下参数：

响应包含以 UTF8 和 Base 64url 编码的 SAML 令牌。

• 来自 OBO 调用的 SAML 断言的 SubjectConfirmationData：如果目标应用程序需要一Recipient个SubjectConfirmationData值，则必须将该值配置为资源应用程序配置中的第一个非wildcard 回复 URL。 由于默认回复 URL 不用于确定 Recipient 值，因此可能需要在应用程序配置中重新排序回复 URL，以确保使用第一个非wildcard 回复 URL。 有关详细信息，请参阅 回复 URL。
• SubjectConfirmationData 节点：节点不能包含属性 InResponseTo ，因为它不是 SAML 响应的一部分。 接收 SAML 令牌的应用程序必须能够在没有 InResponseTo 属性的情况下接受 SAML 断言。
• API 权限：必须在中间层应用程序 上添加必要的 API 权限 ，以允许访问 SAML 应用程序，以便它可以请求 /.default SAML 应用程序范围的令牌。
• 同意：必须授予同意才能接收 SAML 令牌，其中包含 OAuth 流上的用户数据。 有关信息，请参阅 获取中间层应用程序的同意。

• token_type：持有者
• 到期时间：3296
• ext_expires_in：0
• 过期时间：1529627844
• 资源：https://api.contoso.com
• access_token：<SAML 断言>
• issued_token_type：urn：ietf：params：oauth：token-type：saml2
• refresh_token：<刷新令牌>

OBO 流的目标是确保获得相应许可，以便客户端应用可以调用中间层应用，并且中间层应用有权调用后端资源。 根据应用程序的体系结构或使用情况，应考虑以下事项以确保 OBO 流成功：

中间层应用程序将客户端添加到其清单中的 已知客户端应用程序列表 （knownClientApplications）。 如果客户端触发了同意提示，则同意流既适用于自身，又是中间层应用程序。 在Microsoft标识平台上，这是使用作用域完成的.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。 为此，管理员可以在其租户中找到中间层应用程序，打开“所需的权限”页面，然后选择为应用授予权限。 若要了解有关管理员同意的详细信息，请参阅 同意和权限文档。

在某些情况下，只能有一对中间层和前端客户端。 在此方案中，可以更轻松地将此应用程序设为单个应用程序，从而完全否定对中间层应用程序的需求。 若要在前端和 Web API 之间进行身份验证，可以使用 cookie、id_token 或为应用程序本身请求的访问令牌。 然后，从此单一应用程序请求同意后端资源。

详细了解 OAuth 2.0 协议和使用客户端凭据执行服务到服务身份验证的其他方法。

• Microsoft标识平台中的 OAuth 2.0 客户端凭据授予
• Microsoft标识平台中的 OAuth 2.0 代码流
• 使用 /.default 范围