代理流中使用委托用户标识的服务到服务调用Service-to-service calls that use delegated user identity in the On-Behalf-Of flow

重要

Microsoft 标识平台 (v2.0)Azure Active Directory (Azure AD) 开发人员平台 (v1.0) 演变而来。Microsoft identity platform (v2.0) is an evolution of the Azure Active Directory (Azure AD) developer platform (v1.0). 开发人员可以通过它来生成应用程序,从而可以采用所有 Microsoft 标识登录,以及获取令牌来调用 Microsoft Graph 等 Microsoft API 或开发人员生成的 API。It allows developers to build applications that sign in all Microsoft identities and get tokens to call Microsoft APIs such as Microsoft Graph or APIs that developers have built. 本内容适用于版本较旧的 Azure AD v1.0 终结点。This content is for the older, Azure AD v1.0 endpoint. 建议对新项目使用 v2.0 终结点。We recommend that you use the v2.0 endpoint for new projects. 有关详细信息,请参阅为什么要更新到 Microsoft 标识平台 (v2.0)?For more info, read Why update to Microsoft identity platform (v2.0)? 以及 Microsoft 标识平台限制as well as Microsoft identity platform limitations.

OAuth 2.0 代理 (OBO) 流使调用服务或 Web API 的应用程序能够将用户身份验证传递给其他服务或 Web API。The OAuth 2.0 On-Behalf-Of (OBO) flow enables an application that invokes a service or web API to pass user authentication to another service or web API. OBO 流通过请求链传播委托用户权标识和权限。The OBO flow propagates the delegated user identity and permissions through the request chain. 要使中间层服务向下游服务发出身份验证请求,该服务必须代表用户保护 Azure Active Directory (Azure AD) 提供的访问令牌。For the middle-tier service to make authenticated requests to the downstream service, it must secure an access token from Azure Active Directory (Azure AD) on behalf of the user.

重要

从 2018 年 5 月起,id_token 不能用于代理流。As of May 2018, an id_token can't be used for the On-Behalf-Of flow. 单页应用 (SPA) 必须将访问令牌传递给中间层机密客户端,才能执行 OBO 流。Single-page apps (SPAs) must pass an access token to a middle-tier confidential client to perform OBO flows. 有关能够执行代理调用的客户端的更多详细信息,请参阅限制For more detail about the clients that can perform On-Behalf-Of calls, see limitations.

代理流示意图On-Behalf-Of flow diagram

在使用 OAuth 2.0 授权代码授权流的应用程序上对用户进行身份验证后,启动 OBO 流。The OBO flow starts after the user has been authenticated on an application that uses the OAuth 2.0 authorization code grant flow. 此时,应用程序将访问令牌(令牌 A)发送到包含用户声明并同意访问 API A 的中间层 Web API (API A)。然后,API A 向下游 Web API (API B) 发出经过身份验证的请求。At that point, the application sends an access token (token A) to the middle-tier web API (API A) containing the user's claims and consent to access API A. Next, API A makes an authenticated request to the downstream web API (API B).

这些步骤构成了代理流:显示 OAuth2.0 代理流中的步骤These steps constitute the On-Behalf-Of flow: Shows the steps in the OAuth2.0 On-Behalf-Of flow

  1. 客户端应用程序使用令牌 A 向 API A 发出请求。The client application makes a request to API A with the token A.
  2. API A 向 Azure AD 令牌颁发终结点进行身份验证并请求访问 API B 的令牌。API A authenticates to the Azure AD token issuance endpoint and requests a token to access API B.
  3. Azure AD 令牌颁发终结点使用令牌 A 验证 API A 的凭据,并颁发访问 API B 的令牌(令牌 B)。The Azure AD token issuance endpoint validates API A's credentials with token A and issues the access token for API B (token B).
  4. 向 API B 发出的请求在授权标头中包含令牌 B。The request to API B contains token B in the authorization header.
  5. API B 返回受保护资源中的数据。API B returns data from the secured resource.

备注

在用于请求下游服务的令牌的访问令牌中,受众声明必须是发出 OBO 请求的服务 ID。The audience claim in an access token used to request a token for a downstream service must be the ID of the service making the OBO request. 该令牌还必须使用 Azure Active Directory 全局签名密钥(这是通过门户中的“应用注册”注册的应用程序的默认密钥)进行签名。The token also must be signed with the Azure Active Directory global signing key (which is the default for applications registered via App registrations in the portal).

在 Azure AD 中注册应用程序和服务Register the application and service in Azure AD

在 Azure AD 中注册中间层服务和客户端应用程序。Register both the middle-tier service and the client application in Azure AD.

注册中间层服务Register the middle-tier service

  1. 登录到 Azure 门户Sign in to the Azure portal.
  2. 在顶部栏中选择帐户,并在“目录”列表下为应用程序选择 Active Directory 租户。On the top bar, select your account and look under the Directory list to select an Active Directory tenant for your application.
  3. 在左窗格中,选择“更多服务”,然后选择“Azure Active Directory” 。Select More Services on the left pane and choose Azure Active Directory.
  4. 依次选择“应用注册”、“新建注册” 。Select App registrations and then New registration.
  5. 输入应用程序的友好名称,并选择应用程序类型。Enter a friendly name for the application and select the application type.
  6. 在“支持的帐户类型”下,选择“任何组织目录中的帐户”。 Under Supported account types, select Accounts in any organizational directory.
  7. 将重定向 URI 设置为基 URL。Set the redirect URI to the base URL.
  8. 选择“注册”以创建应用程序。Select Register to create the application.
  9. 在 Azure 门户中,选择应用程序,然后选择“证书和机密”。In the Azure portal, choose your application and select Certificates & secrets.
  10. 选择“新建客户端密码”并添加持续时间为一年或两年的机密。Select New client secret and add a secret with a duration of either one year or two years.
  11. 保存此页时,Azure 门户将显示机密值。When you save this page, the Azure portal displays the secret value. 复制机密值并将其保存在安全位置。Copy and save the secret value in a safe location.
  12. 在应用的“公开 API”页面中创建一个基于应用程序的作用域,然后单击“添加作用域”。Create a scope on your application in the Expose an API page for your app, and clicking "Add a scope". 门户可能要求你也创建应用程序 ID URI。The Portal may require you to create an application ID URI as well.

重要

在实现中配置应用程序设置时需要此机密。You need the secret to configure the application settings in your implementation. 此机密值不会再次显示,并且无法通过任何其他方式检索。This secret value is not displayed again, and it isn't retrievable by any other means. 因此,当它在 Azure 门户中可见时请立即记录。Record it as soon as it is visible in the Azure portal.

注册客户端应用程序Register the client application

  1. 登录 Azure 门户Sign in to the Azure portal.
  2. 在顶部栏中选择帐户,并在“目录”列表下为应用程序选择 Active Directory 租户。On the top bar, select your account and look under the Directory list to select an Active Directory tenant for your application.
  3. 在左窗格中,选择“更多服务”,然后选择“Azure Active Directory” 。Select More Services on the left pane and choose Azure Active Directory.
  4. 依次选择“应用注册”、“新建注册” 。Select App registrations and then New registration.
  5. 输入应用程序的友好名称,并选择应用程序类型。Enter a friendly name for the application and select the application type.
  6. 在“支持的帐户类型”下,选择“任何组织目录中的帐户”。 Under Supported account types, select Accounts in any organizational directory.
  7. 将重定向 URI 设置为基 URL。Set the redirect URI to the base URL.
  8. 选择“注册”以创建应用程序。Select Register to create the application.
  9. 为应用程序配置权限。Configure permissions for your application. 在“API 权限”中,依次选择“添加权限”、“我的 API”。In API permissions, select Add a permission and then My APIs.
  10. 在文本字段中键入中间层服务的名称。Type the name of the middle-tier service in the text field.
  11. 选择“选择权限”,然后选择在注册中间层的最后一步中创建的作用域。Choose Select Permissions and then select the scope you created in the last step of registering the middle-tier.

配置已知的客户端应用程序Configure known client applications

在此方案中,中间层服务在没有用户干预的情况下,需要获取用户对访问下游 API 的许可。In this scenario, the middle-tier service needs to obtain the user's consent to access the downstream API without a user interaction. 在身份验证过程的许可步骤中必须提前显示授权访问下游 API 的选项。The option to grant access to the downstream API must be presented up front as part of the consent step during authentication.

按照以下步骤将 Azure AD 中的客户端应用注册与中间层服务的注册显式绑定。Follow the steps below to explicitly bind the client app's registration in Azure AD with the middle-tier service's registration. 此操作将客户端和中间层所需的许可合并到一个对话框中。This operation merges the consent required by both the client and middle-tier into a single dialog.

  1. 转到中间层服务注册,然后选择“清单”以打开清单编辑器。Go to the middle-tier service registration and select Manifest to open the manifest editor.
  2. 找到 knownClientApplications 数组属性,然后将客户端应用程序的客户端 ID 添加为元素。Locate the knownClientApplications array property and add the client ID of the client application as an element.
  3. 选择“保存”以保存清单。Save the manifest by selecting Save.

服务到服务访问令牌请求Service-to-service access token request

要请求访问令牌,请使用以下参数向特定于租户的 Azure AD 终结点发出 HTTP POST:To request an access token, make an HTTP POST to the tenant-specific Azure AD endpoint with the following parameters:

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

客户端应用程序由共享密钥或证书提供保护。The client application is secured either by a shared secret or by a certificate.

第一种情况:使用共享机密访问令牌请求First case: Access token request with a shared secret

使用共享密钥时,服务到服务访问令牌请求包含以下参数:When using a shared secret, a service-to-service access token request contains the following parameters:

参数Parameter 类型Type 说明Description
grant_typegrant_type 必需required 令牌请求的类型。The type of the token request. OBO 请求使用 JSON Web 令牌 (JWT),因此值必须是 urn:ietf:params:oauth:grant-type:jwt-bearer。An OBO request uses a JSON Web Token (JWT) so the value must be urn:ietf:params:oauth:grant-type:jwt-bearer.
assertionassertion 必需required 请求中使用的访问令牌值。The value of the access token used in the request.
client_idclient_id 必需required 在注册到 Azure AD 期间分配给调用服务的应用 ID。The app ID assigned to the calling service during registration with Azure AD. 要在 Azure 门户中查找应用 ID,请选择“Active Directory”,选择目录,然后选择应用程序名称。To find the app ID in the Azure portal, select Active Directory, choose the directory, and then select the application name.
client_secretclient_secret 必需required 在 Azure AD 中为调用服务注册的密钥。The key registered for the calling service in Azure AD. 注册时应已记下此值。This value should have been noted at the time of registration.
resourceresource 必需required 接收服务(受保护资源)的应用 ID URI。The app ID URI of the receiving service (secured resource). 要在 Azure 门户中查找应用 ID URI,请选择“Active Directory”并选择目录。To find the app ID URI in the Azure portal, select Active Directory and choose the directory. 选择应用程序名称,选择“所有设置”,然后选择“属性” 。Select the application name, choose All settings, and then select Properties.
requested_token_userequested_token_use 必需required 指定应如何处理请求。Specifies how the request should be processed. 在代理流中,该值必须是 on_behalf_ofIn the On-Behalf-Of flow, the value must be on_behalf_of.
scopescope 必需required 空格分隔的令牌请求作用域的列表。A space separated list of scopes for the token request. 对于 OpenID Connect,必须指定范围 openidFor OpenID Connect, the scope openid must be specified.

示例Example

以下 HTTP POST 请求 https://microsoftgraph.chinacloudapi.cn Web API 的访问令牌。The following HTTP POST requests an access token for the https://microsoftgraph.chinacloudapi.cn web API. client_id 标识请求访问令牌的服务。The client_id identifies the service that requests the access token.

// line breaks for legibility only

POST /oauth2/token HTTP/1.1
Host: login.partner.microsoftonline.cn
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=625391af-c675-43e5-8e44-edd3e30ceb15
&client_secret=0Y1W%2BY3yYb3d9N8vSjvm8WrGzVZaAaHbHHcGbcgG%2BoI%3D
&resource=https%3A%2F%2Fmicrosoftgraph.chinacloudapi.cn
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.ewogICJhdWQiOiAiaHR0cHM6Ly9ncmFwaC5taWNyb3NvZnQuY29tIiwKICAiaXNzIjogImh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzI2MDM5Y2NlLTQ4OWQtNDAwMi04MjkzLTViMGM1MTM0ZWFjYi8iLAogICJpYXQiOiAxNDkzNDIzMTY4LAogICJuYmYiOiAxNDkzNDIzMTY4LAogICJleHAiOiAxNDkzNDY2OTUxLAogICJhY3IiOiAiMSIsCiAgImFpbyI6ICJBU1FBMi84REFBQUE1NnZGVmp0WlNjNWdBVWwrY1Z0VFpyM0VvV2NvZEoveWV1S2ZqcTZRdC9NPSIsCiAgImFtciI6IFsKICAgICJwd2QiCiAgXSwKICAiYXBwaWQiOiAiNjI1MzkxYWYtYzY3NS00M2U1LThlNDQtZWRkM2UzMGNlYjE1IiwKICAiYXBwaWRhY3IiOiAiMSIsCiAgImVfZXhwIjogMzAyNjgzLAogICJmYW1pbHlfbmFtZSI6ICJUZXN0IiwKICAiZ2l2ZW5fbmFtZSI6ICJOYXZ5YSIsCiAgImlwYWRkciI6ICIxNjcuMjIwLjEuMTc3IiwKICAibmFtZSI6ICJOYXZ5YSBUZXN0IiwKICAib2lkIjogIjFjZDRiY2FjLWI4MDgtNDIzYS05ZTJmLTgyN2ZiYjFiYjczOSIsCiAgInBsYXRmIjogIjMiLAogICJwdWlkIjogIjEwMDMzRkZGQTEyRUQ3RkUiLAogICJzY3AiOiAiVXNlci5SZWFkIiwKICAic3ViIjogIjNKTUlaSWJlYTc1R2hfWHdDN2ZzX0JDc3kxa1l1ekZKLTUyVm1Zd0JuM3ciLAogICJ0aWQiOiAiMjYwMzljY2UtNDg5ZC00MDAyLTgyOTMtNWIwYzUxMzRlYWNiIiwKICAidW5pcXVlX25hbWUiOiAibmF2eWFAZGRvYmFsaWFub3V0bG9vay5vbm1pY3Jvc29mdC5jb20iLAogICJ1cG4iOiAibmF2eWFAZGRvYmFsaWFub3V0bG9vay5vbm1pY3Jvc29mdC5jb20iLAogICJ1dGkiOiAieEN3ZnpoYS1QMFdKUU9MeENHZ0tBQSIsCiAgInZlciI6ICIxLjAiCn0.cqmUVjfVbqWsxJLUI1Z4FRx1mNQAHP-L0F4EMN09r8FY9bIKeO-0q1eTdP11Nkj_k4BmtaZsTcK_mUygdMqEp9AfyVyA1HYvokcgGCW_Z6DMlVGqlIU4ssEkL9abgl1REHElPhpwBFFBBenOk9iHddD1GddTn6vJbKC3qAaNM5VarjSPu50bVvCrqKNvFixTb5bbdnSz-Qr6n6ACiEimiI1aNOPR2DeKUyWBPaQcU5EAK0ef5IsVJC1yaYDlAcUYIILMDLCD9ebjsy0t9pj_7lvjzUSrbMdSCCdzCqez_MSNxrk1Nu9AecugkBYp3UVUZOIyythVrj6-sVvLZKUutQ
&requested_token_use=on_behalf_of
&scope=openid

第二种情况:使用证书访问令牌请求Second case: Access token request with a certificate

使用证书的服务到服务访问令牌请求包含以下参数:A service-to-service access token request with a certificate contains the following parameters:

参数Parameter 类型Type 说明Description
grant_typegrant_type 必需required 令牌请求的类型。The type of the token request. OBO 请求使用 JWT 访问令牌,因此值必须是 urn:ietf:params:oauth:grant-type:jwt-bearer。An OBO request uses a JWT access token so the value must be urn:ietf:params:oauth:grant-type:jwt-bearer.
assertionassertion 必需required 请求中使用的令牌值。The value of the token used in the request.
client_idclient_id 必需required 在注册到 Azure AD 期间分配给调用服务的应用 ID。The app ID assigned to the calling service during registration with Azure AD. 要在 Azure 门户中查找应用 ID,请选择“Active Directory”,选择目录,然后选择应用程序名称。To find the app ID in the Azure portal, select Active Directory, choose the directory, and then select the application name.
client_assertion_typeclient_assertion_type 必需required 值必须是 urn:ietf:params:oauth:client-assertion-type:jwt-bearerThe value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertionclient_assertion 必需required JSON Web 令牌使用作为凭据向应用程序注册的证书进行创建和签名。A JSON Web Token that you create and sign with the certificate you registered as credentials for your application. 请参阅证书凭据了解断言格式以及如何注册证书。See certificate credentials to learn about assertion format and about how to register your certificate.
resourceresource 必需required 接收服务(受保护资源)的应用 ID URI。The app ID URI of the receiving service (secured resource). 要在 Azure 门户中查找应用 ID URI,请选择“Active Directory”并选择目录。To find the app ID URI in the Azure portal, select Active Directory and choose the directory. 选择应用程序名称,选择“所有设置”,然后选择“属性” 。Select the application name, choose All settings, and then select Properties.
requested_token_userequested_token_use 必需required 指定应如何处理请求。Specifies how the request should be processed. 在代理流中,该值必须是 on_behalf_ofIn the On-Behalf-Of flow, the value must be on_behalf_of.
scopescope 必需required 空格分隔的令牌请求作用域的列表。A space separated list of scopes for the token request. 对于 OpenID Connect,必须指定范围 openidFor OpenID Connect, the scope openid must be specified.

这些参数与共享密钥请求几乎相同,只是 client_secret parameter 被以下两个参数替换:client_assertion_typeclient_assertionThese parameters are almost the same as with the request by shared secret except that the client_secret parameter is replaced by two parameters: client_assertion_type and client_assertion.

示例Example

以下 HTTP POST 请求具有证书的 https://microsoftgraph.chinacloudapi.cn Web API 的访问令牌。The following HTTP POST requests an access token for the https://microsoftgraph.chinacloudapi.cn web API with a certificate. client_id 标识请求访问令牌的服务。The client_id identifies the service that requests the access token.

// line breaks for legibility only

POST /oauth2/token HTTP/1.1
Host: login.partner.microsoftonline.cn
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=625391af-c675-43e5-8e44-edd3e30ceb15
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&resource=https%3A%2F%2Fmicrosoftgraph.chinacloudapi.cn
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiJodHRwczovL2Rkb2JhbGlhbm91dGxvb2sub25taWNyb3NvZnQuY29tLzE5MjNmODYyLWU2ZGMtNDFhMy04MWRhLTgwMmJhZTAwYWY2ZCIsImlzcyI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzI2MDM5Y2NlLTQ4OWQtNDAwMi04MjkzLTViMGM1MTM0ZWFjYi8iLCJpYXQiOjE0OTM0MjMxNTIsIm5iZiI6MTQ5MzQyMzE1MiwiZXhwIjoxNDkzNDY2NjUyLCJhY3IiOiIxIiwiYWlvIjoiWTJaZ1lCRFF2aTlVZEc0LzM0L3dpQndqbjhYeVp4YmR1TFhmVE1QeG8yYlN2elgreHBVQSIsImFtciI6WyJwd2QiXSwiYXBwaWQiOiJiMzE1MDA3OS03YmViLTQxN2YtYTA2YS0zZmRjNzhjMzI1NDUiLCJhcHBpZGFjciI6IjAiLCJlX2V4cCI6MzAyNDAwLCJmYW1pbHlfbmFtZSI6IlRlc3QiLCJnaXZlbl9uYW1lIjoiTmF2eWEiLCJpcGFkZHIiOiIxNjcuMjIwLjEuMTc3IiwibmFtZSI6Ik5hdnlhIFRlc3QiLCJvaWQiOiIxY2Q0YmNhYy1iODA4LTQyM2EtOWUyZi04MjdmYmIxYmI3MzkiLCJwbGF0ZiI6IjMiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJEVXpYbkdKMDJIUk0zRW5pbDFxdjZCakxTNUllQy0tQ2ZpbzRxS1MzNEc4IiwidGlkIjoiMjYwMzljY2UtNDg5ZC00MDAyLTgyOTMtNWIwYzUxMzRlYWNiIiwidW5pcXVlX25hbWUiOiJuYXZ5YUBkZG9iYWxpYW5vdXRsb29rLm9ubWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hdnlhQGRkb2JhbGlhbm91dGxvb2sub25taWNyb3NvZnQuY29tIiwidmVyIjoiMS4wIn0.R-Ke-XO7lK0r5uLwxB8g5CrcPAwRln5SccJCfEjU6IUqpqcjWcDzeDdNOySiVPDU_ZU5knJmzRCF8fcjFtPsaA4R7vdIEbDuOur15FXSvE8FvVSjP_49OH6hBYqoSUAslN3FMfbO6Z8YfCIY4tSOB2I6ahQ_x4ZWFWglC3w5mK-_4iX81bqi95eV4RUKefUuHhQDXtWhrSgIEC0YiluMvA4TnaJdLq_tWXIc4_Tq_KfpkvI004ONKgU7EAMEr1wZ4aDcJV2yf22gQ1sCSig6EGSTmmzDuEPsYiyd4NhidRZJP4HiiQh-hePBQsgcSgYGvz9wC6n57ufYKh2wm_Ti3Q
&requested_token_use=on_behalf_of
&scope=openid

服务到服务访问令牌响应Service-to-service access token response

成功响应是具有以下参数的 JSON OAuth 2.0 响应:A success response is a JSON OAuth 2.0 response with the following parameters:

参数Parameter 说明Description
token_typetoken_type 指示令牌类型值。Indicates the token type value. Azure AD 唯一支持的类型是 Bearer 。The only type that Azure AD supports is Bearer. 有关持有者令牌的详细信息,请参阅 OAuth 2.0 授权框架:持有者令牌用法 (RFC 6750)For more information about bearer tokens, see the OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750).
scopescope 令牌中授予的访问权限的范围。The scope of access granted in the token.
expires_inexpires_in 访问令牌有效的时间长度(以秒为单位)。The length of time the access token is valid (in seconds).
expires_onexpires_on 访问令牌的过期时间。The time when the access token expires. 该日期表示为自 1970-01-01T0:0:0Z UTC 至过期时间的秒数。The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time. 此值用于确定缓存令牌的生存期。This value is used to determine the lifetime of cached tokens.
resourceresource 接收服务(受保护资源)的应用 ID URI。The app ID URI of the receiving service (secured resource).
access_tokenaccess_token 请求的访问令牌。The requested access token. 调用方服务可以使用此令牌向接收方服务进行身份验证。The calling service can use this token to authenticate to the receiving service.
id_tokenid_token 请求的 ID 令牌。The requested ID token. 调用服务可以使用此令牌验证用户的身份,并开始与用户建立会话。The calling service can use this token to verify the user's identity and begin a session with the user.
refresh_tokenrefresh_token 所请求的访问令牌的刷新令牌。The refresh token for the requested access token. 当前访问令牌过期后,调用方服务可以使用此令牌请求另一个访问令牌。The calling service can use this token to request another access token after the current access token expires.

成功响应示例Success response example

以下示例演示对 https://microsoftgraph.chinacloudapi.cn Web API 的访问令牌请求的成功响应。The following example shows a success response to a request for an access token for the https://microsoftgraph.chinacloudapi.cn web API.

{
    "token_type":"Bearer",
    "scope":"User.Read",
    "expires_in":"43482",
    "ext_expires_in":"302683",
    "expires_on":"1493466951",
    "not_before":"1493423168",
    "resource":"https://microsoftgraph.chinacloudapi.cn",
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiJodHRwczovL2dyYXBoLndpbmRvd3MubmV0IiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvMjYwMzljY2UtNDg5ZC00MDAyLTgyOTMtNWIwYzUxMzRlYWNiLyIsImlhdCI6MTQ5MzQyMzE2OCwibmJmIjoxNDkzNDIzMTY4LCJleHAiOjE0OTM0NjY5NTEsImFjciI6IjEiLCJhaW8iOiJBU1FBMi84REFBQUE1NnZGVmp0WlNjNWdBVWwrY1Z0VFpyM0VvV2NvZEoveWV1S2ZqcTZRdC9NPSIsImFtciI6WyJwd2QiXSwiYXBwaWQiOiI2MjUzOTFhZi1jNjc1LTQzZTUtOGU0NC1lZGQzZTMwY2ViMTUiLCJhcHBpZGFjciI6IjEiLCJlX2V4cCI6MzAyNjgzLCJmYW1pbHlfbmFtZSI6IlRlc3QiLCJnaXZlbl9uYW1lIjoiTmF2eWEiLCJpcGFkZHIiOiIxNjcuMjIwLjEuMTc3IiwibmFtZSI6Ik5hdnlhIFRlc3QiLCJvaWQiOiIxY2Q0YmNhYy1iODA4LTQyM2EtOWUyZi04MjdmYmIxYmI3MzkiLCJwbGF0ZiI6IjMiLCJwdWlkIjoiMTAwMzNGRkZBMTJFRDdGRSIsInNjcCI6IlVzZXIuUmVhZCIsInN1YiI6IjNKTUlaSWJlYTc1R2hfWHdDN2ZzX0JDc3kxa1l1ekZKLTUyVm1Zd0JuM3ciLCJ0aWQiOiIyNjAzOWNjZS00ODlkLTQwMDItODI5My01YjBjNTEzNGVhY2IiLCJ1bmlxdWVfbmFtZSI6Im5hdnlhQGRkb2JhbGlhbm91dGxvb2sub25taWNyb3NvZnQuY29tIiwidXBuIjoibmF2eWFAZGRvYmFsaWFub3V0bG9vay5vbm1pY3Jvc29mdC5jb20iLCJ1dGkiOiJ4Q3dmemhhLVAwV0pRT0x4Q0dnS0FBIiwidmVyIjoiMS4wIn0.cqmUVjfVbqWsxJLUI1Z4FRx1mNQAHP-L0F4EMN09r8FY9bIKeO-0q1eTdP11Nkj_k4BmtaZsTcK_mUygdMqEp9AfyVyA1HYvokcgGCW_Z6DMlVGqlIU4ssEkL9abgl1REHElPhpwBFFBBenOk9iHddD1GddTn6vJbKC3qAaNM5VarjSPu50bVvCrqKNvFixTb5bbdnSz-Qr6n6ACiEimiI1aNOPR2DeKUyWBPaQcU5EAK0ef5IsVJC1yaYDlAcUYIILMDLCD9ebjsy0t9pj_7lvjzUSrbMdSCCdzCqez_MSNxrk1Nu9AecugkBYp3UVUZOIyythVrj6-sVvLZKUutQ",
    "refresh_token":"AQABAAAAAABnfiG-mA6NTae7CdWW7QfdjKGu9-t1scy_TDEmLi4eLQMjJGt_nAoVu6A4oSu1KsRiz8XyQIPKQxSGfbf2FoSK-hm2K8TYzbJuswYusQpJaHUQnSqEvdaCeFuqXHBv84wjFhuanzF9dQZB_Ng5za9xKlUENrNtlq9XuLNVKzxEyeUM7JyxzdY7JiEphWImwgOYf6II316d0Z6-H3oYsFezf4Xsjz-MOBYEov0P64UaB5nJMvDyApV-NWpgklLASfNoSPGb67Bc02aFRZrm4kLk-xTl6eKE6hSo0XU2z2t70stFJDxvNQobnvNHrAmBaHWPAcC3FGwFnBOojpZB2tzG1gLEbmdROVDp8kHEYAwnRK947Py12fJNKExUdN0njmXrKxNZ_fEM33LHW1Tf4kMX_GvNmbWHtBnIyG0w5emb-b54ef5AwV5_tGUeivTCCysgucEc-S7G8Cz0xNJ_BOiM_4bAv9iFmrm9STkltpz0-Tftg8WKmaJiC0xXj6uTf4ZkX79mJJIuuM7XP4ARIcLpkktyg2Iym9jcZqymRkGH2Rm9sxBwC4eeZXM7M5a7TJ-5CqOdfuE3sBPq40RdEWMFLcrAzFvP0VDR8NKHIrPR1AcUruat9DETmTNJukdlJN3O41nWdZOVoJM-uKN3uz2wQ2Ld1z0Mb9_6YfMox9KTJNzRzcL52r4V_y3kB6ekaOZ9wQ3HxGBQ4zFt-2U0mSszIAA",
    "id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiI2MjUzOTFhZi1jNjc1LTQzZTUtOGU0NC1lZGQzZTMwY2ViMTUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC8yNjAzOWNjZS00ODlkLTQwMDItODI5My01YjBjNTEzNGVhY2IvIiwiaWF0IjoxNDkzNDIzMTY4LCJuYmYiOjE0OTM0MjMxNjgsImV4cCI6MTQ5MzQ2Njk1MSwiYW1yIjpbInB3ZCJdLCJmYW1pbHlfbmFtZSI6IlRlc3QiLCJnaXZlbl9uYW1lIjoiTmF2eWEiLCJpcGFkZHIiOiIxNjcuMjIwLjEuMTc3IiwibmFtZSI6Ik5hdnlhIFRlc3QiLCJvaWQiOiIxY2Q0YmNhYy1iODA4LTQyM2EtOWUyZi04MjdmYmIxYmI3MzkiLCJwbGF0ZiI6IjMiLCJzdWIiOiJEVXpYbkdKMDJIUk0zRW5pbDFxdjZCakxTNUllQy0tQ2ZpbzRxS1MzNEc4IiwidGlkIjoiMjYwMzljY2UtNDg5ZC00MDAyLTgyOTMtNWIwYzUxMzRlYWNiIiwidW5pcXVlX25hbWUiOiJuYXZ5YUBkZG9iYWxpYW5vdXRsb29rLm9ubWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hdnlhQGRkb2JhbGlhbm91dGxvb2sub25taWNyb3NvZnQuY29tIiwidXRpIjoieEN3ZnpoYS1QMFdKUU9MeENHZ0tBQSIsInZlciI6IjEuMCJ9."
}

错误响应示例Error response example

Azure AD 令牌终结点在尝试获取使用条件访问策略(例如,多重身份验证)设置的下游 API 的访问令牌时,会返回错误响应。The Azure AD token endpoint returns an error response when it tries to acquire an access token for a downstream API that is set with a Conditional Access policy (for example, multi-factor authentication). 中间层服务应向客户端应用程序显示此错误,以便客户端应用程序可以提供用户交互,以满足条件访问策略。The middle-tier service should surface this error to the client application so that the client application can provide the user interaction to satisfy the Conditional Access policy.

{
    "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 multi-factor authentication to access 'bf8d80f9-9098-4972-b203-500f535113b1'.\r\nTrace ID: b72a68c3-0926-4b8e-bc35-3150069c2800\r\nCorrelation ID: 73d656cf-54b1-4eb2-b429-26d8165a52d7\r\nTimestamp: 2017-05-01 22:43:20Z",
    "error_codes":[50079],
    "timestamp":"2017-05-01 22:43:20Z",
    "trace_id":"b72a68c3-0926-4b8e-bc35-3150069c2800",
    "correlation_id":"73d656cf-54b1-4eb2-b429-26d8165a52d7",
    "claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"9ab03e19-ed42-4168-b6b7-7001fb3e933a\"]}}}"
}

使用访问令牌访问受保护资源Use the access token to access the secured resource

中间层服务可以通过在 Authorization 标头中设置令牌,使用获取的访问令牌向下游 Web API 发出经过身份验证的请求。The middle-tier service can use the acquired access token to make authenticated requests to the downstream web API by setting the token in the Authorization header.

示例Example

GET /me?api-version=2013-11-08 HTTP/1.1
Host: microsoftgraph.chinacloudapi.cn
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

使用 OAuth2.0 OBO 流获得的 SAML 断言SAML assertions obtained with an OAuth2.0 OBO flow

某些基于 OAuth 的 Web 服务需要访问在非交互式流中接受 SAML 断言的其他 Web 服务 API。Some OAuth-based web services need to access other web service APIs that accept SAML assertions in non-interactive flows. Azure Active Directory 可以提供 SAML 断言,以响应将基于 SAML 的 Web 服务用作目标资源的代理流。Azure Active Directory can provide a SAML assertion in response to an On-Behalf-Of flow that uses a SAML-based web service as a target resource.

备注

这是非标准的 OAuth 2.0 代理流扩展,它允许基于 OAuth2 的应用程序访问使用 SAML 令牌的 Web 服务 API 终结点。This is a non-standard extension to the OAuth 2.0 On-Behalf-Of flow that allows an OAuth2-based application to access web service API endpoints that consume SAML tokens.

提示

当从前端 Web 应用程序调用受 SAML 保护的 Web 服务时,只需调用 API 并使用用户的现有会话启动正常的交互式身份验证流。When you call a SAML-protected web service from a front-end web application, you can simply call the API and initiate a normal interactive authentication flow with the user's existing session. 当服务到服务调用需要 SAML 令牌来提供用户上下文时,只需使用 OBO 流。You only need to use an OBO flow when a service-to-service call requires a SAML token to provide user context.

使用带共享密钥的 OBO 请求获取 SAML 令牌Obtain a SAML token by using an OBO request with a shared secret

SAML 断言的服务到服务请求包含以下参数:A service-to-service request for a SAML assertion contains the following parameters:

参数Parameter 类型Type 说明Description
grant_typegrant_type 必需required 令牌请求的类型。The type of the token request. 对于使用 JWT 的请求,该值必须是 urn:ietf:params:oauth:grant-type:jwt-bearer。For a request that uses a JWT, the value must be urn:ietf:params:oauth:grant-type:jwt-bearer.
assertionassertion 必需required 请求中使用的访问令牌值。The value of the access token used in the request.
client_idclient_id 必需required 在注册到 Azure AD 期间分配给调用服务的应用 ID。The app ID assigned to the calling service during registration with Azure AD. 要在 Azure 门户中查找应用 ID,请选择“Active Directory”,选择目录,然后选择应用程序名称。To find the app ID in the Azure portal, select Active Directory, choose the directory, and then select the application name.
client_secretclient_secret 必需required 在 Azure AD 中为调用服务注册的密钥。The key registered for the calling service in Azure AD. 注册时应已记下此值。This value should have been noted at the time of registration.
resourceresource 必需required 接收服务(受保护资源)的应用 ID URI。The app ID URI of the receiving service (secured resource). 这是将成为 SAML 令牌受众的资源。This is the resource that will be the Audience of the SAML token. 要在 Azure 门户中查找应用 ID URI,请选择“Active Directory”并选择目录。To find the app ID URI in the Azure portal, select Active Directory and choose the directory. 选择应用程序名称,选择“所有设置”,然后选择“属性” 。Select the application name, choose All settings, and then select Properties.
requested_token_userequested_token_use 必需required 指定应如何处理请求。Specifies how the request should be processed. 在代理流中,该值必须是 on_behalf_ofIn the On-Behalf-Of flow, the value must be on_behalf_of.
requested_token_typerequested_token_type 必需required 指定请求令牌的类型。Specifies the type of token requested. 值可以是 urn:ietf:params:oauth:token-type:saml2 或 urn:ietf:params:oauth:token-type:saml1,具体取决于访问资源的要求 。The value can be urn:ietf:params:oauth:token-type:saml2 or urn:ietf:params:oauth:token-type:saml1 depending on the requirements of the accessed resource.

响应包含以 UTF8 和 Base64url 编码的 SAML 令牌。The response contains a SAML token encoded in UTF8 and Base64url.

  • 源自 OBO 调用的 SAML 断言的 SubjectConfirmationData:如果目标应用程序需要 SubjectConfirmationData 中的接收方值,则该值必须是资源应用程序配置中的非通配符回复 URL。SubjectConfirmationData for a SAML assertion sourced from an OBO call: If the target application requires a recipient value in SubjectConfirmationData, then the value must be a non-wildcard Reply URL in the resource application configuration.

  • SubjectConfirmationData 节点:此节点不能包含 InResponseTo 属性,因为它不是 SAML 响应的一部分。The SubjectConfirmationData node: The node can't contain an InResponseTo attribute since it's not part of a SAML response. 接收 SAML 令牌的应用程序必须能够在没有 InResponseTo 属性的情况下接受 SAML 断言。The application receiving the SAML token must be able to accept the SAML assertion without an InResponseTo attribute.

  • 许可:必须授予许可,才能接收包含 OAuth 流上用户数据的 SAML 令牌。Consent: Consent must have been granted to receive a SAML token containing user data on an OAuth flow. 有关权限和获取管理员许可的信息,请参阅 Azure Active Directory v1.0 终结点中的权限和许可For information on permissions and obtaining administrator consent, see Permissions and consent in the Azure Active Directory v1.0 endpoint.

使用 SAML 断言进行响应Response with SAML assertion

参数Parameter 说明Description
token_typetoken_type 指示令牌类型值。Indicates the token type value. Azure AD 唯一支持的类型是 Bearer 。The only type that Azure AD supports is Bearer. 有关持有者令牌的详细信息,请参阅 OAuth 2.0 授权框架:持有者令牌用法 (RFC 6750)For more information about bearer tokens, see OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750).
scopescope 令牌中授予的访问权限的范围。The scope of access granted in the token.
expires_inexpires_in 访问令牌有效的时间长度(以秒为单位)。The length of time the access token is valid (in seconds).
expires_onexpires_on 访问令牌的过期时间。The time when the access token expires. 该日期表示为自 1970-01-01T0:0:0Z UTC 至过期时间的秒数。The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time. 此值用于确定缓存令牌的生存期。This value is used to determine the lifetime of cached tokens.
resourceresource 接收服务(受保护资源)的应用 ID URI。The app ID URI of the receiving service (secured resource).
access_tokenaccess_token 返回 SAML 断言的参数。The parameter that returns the SAML assertion.
refresh_tokenrefresh_token 刷新令牌。The refresh token. 当前 SAML 断言过期后,调用方服务可以使用此令牌请求另一个访问令牌。The calling service can use this token to request another access token after the current SAML assertion expires.
  • token_type:持有者token_type: Bearer
  • expires_in:3296expires_in: 3296
  • ext_expires_in:0ext_expires_in: 0
  • expires_on:1529627844expires_on: 1529627844
  • 资源:https://api.contoso.comresource: https://api.contoso.com
  • access_token:<SAML assertion>access_token: <SAML assertion>
  • issued_token_type: urn:ietf:params:oauth:token-type:saml2issued_token_type: urn:ietf:params:oauth:token-type:saml2
  • refresh_token:<Refresh token>refresh_token: <Refresh token>

客户端限制Client limitations

具有通配符回复 URL 的公共客户端无法为 OBO 流使用 id_tokenPublic clients with wildcard reply URLs can't use an id_token for OBO flows. 但是,机密客户端仍可兑现通过隐式授予流获取的访问令牌,即使公共客户端已注册通配符重定向 URI。However, a confidential client can still redeem access tokens acquired through the implicit grant flow even if the public client has a wildcard redirect URI registered.

后续步骤Next steps

详细了解 OAuth 2.0 协议和执行使用客户端凭据的服务到服务身份验证的其他方法:Learn more about the OAuth 2.0 protocol and another way to perform service-to-service authentication that uses client credentials: