你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 Azure Active Directory B2C 自定义策略中定义 OAuth2 技术配置文件

项目
01/11/2024

注意

在 Azure Active Directory B2C 中，自定义策略主要用于解决复杂的情况。在大多数情况下，建议你使用内置用户流。如果尚未这样做，请从 Active Directory B2C 中的自定义策略入门了解自定义策略新手包。

Azure Active Directory B2C (Azure AD B2C) 提供对 OAuth2 协议标识提供者的支持。 OAuth2 是用于授权和委托身份验证的主要协议。有关详细信息，请参阅 RFC 6749 - OAuth 2.0 授权框架。使用 OAuth2 技术配置文件，可以与基于 OAuth2 的标识提供者（例如 Facebook）联合。与标识提供者联合允许用户使用其现有的社交或企业标识登录。

协议

“Protocol”元素的“Name”属性必须设置为 OAuth2。例如，Facebook-OAUTH 技术配置文件的协议为 OAuth2：

<TechnicalProfile Id="Facebook-OAUTH">
  <DisplayName>Facebook</DisplayName>
  <Protocol Name="OAuth2" />
  ...

输入声明

InputClaims 和 InputClaimsTransformations 元素不是必需的。但是，你可能需要向标识提供者发送更多参数。以下示例将值为的 domain_hint 查询字符串参数添加到授权请求。

<InputClaims>
  <InputClaim ClaimTypeReferenceId="domain_hint" DefaultValue="contoso.com" />
</InputClaims>

输出声明

OutputClaims 元素包含 OAuth2 标识提供者返回的声明列表。可能需要将策略中定义的声明名称映射到标识提供者中定义的名称。只要设置了 DefaultValue 属性，就还可以包含标识提供者不会返回的声明。

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。

以下示例演示 Facebook 标识提供者返回的声明：

first_name 声明已映射到 givenName 声明。
last_name 声明已映射到 surname 声明。
没有名称映射的 displayName 声明。
没有名称映射的 email 声明。

技术配置文件还会返回标识提供者不返回的声明：

identityProvider 声明，其中包含标识提供者的名称。
authenticationSource 声明，其默认值为 socialIdpAuthentication。

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="id" />
  <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="first_name" />
  <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="last_name" />
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="email" />
  <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="facebook.com" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" />
</OutputClaims>

授权终结点元数据

Azure AD B2C 将用户定向到 OAuth2 标识提供者 /authorize 终结点时，将开始授权流。调用授权终结点属于流的交互过程，用户会在其中执行操作。此时，系统会要求用户在 OAuth2 标识提供者上完成登录。例如，通过输入用户名和密码。

Azure AD B2C 通过提供从标识提供者处获取访问令牌所需的客户端 ID、范围、重定向 URI 和其他参数，来创建授权请求。本部分介绍授权终结点元数据，该元数据允许配置对标识提供者的 /authorize 终结点的请求。

对授权终结点的请求始终采用 HTTP GET。下面的示例演示了对授权终结点的调用。

GET https://login.contoso.com/oauth/v2/authorization?
client_id=12345
&response_type=code
&response_mode=query
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&scope=profile%20offline_access
&redirect_uri=https%3a%2f%2fabrikam.b2clogin.com%2fabrikam.onmicrosoft.com%2foauth2%2fauthresp
&state=...

下表列出了授权终结点元数据。

特性	必选	说明
`authorization_endpoint`	是	符合 RFC 6749 规范的授权终结点的 URL。
`client_id`	是	标识提供者的应用程序标识符。
`AdditionalRequestQueryParameters`	否	额外的请求查询参数。例如，你可能需要向标识提供者发送更多参数。可以使用逗号分隔符包含多个参数。
`response_mode`	否	标识提供者在将结果发送回 Azure AD B2C 时使用的方法。可能的值：`query`、`form_post`（默认值）或 `fragment`。
`scope`	否	根据 OAuth2 标识提供者规范定义的请求的范围。例如 `openid`、`profile` 和 `email`。
`UsePolicyInRedirectUri`	否	指示在构造重定向 URI 时是否要使用策略。在标识提供者中配置应用程序时，需指定重定向 URI。重定向 URI 指向 Azure AD B2C `https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/oauth2/authresp`。如果指定 `true`，需为每个使用的策略添加重定向 URI。例如：`https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/{policy-name}/oauth2/authresp`。

令牌终结点元数据

用户在标识提供者的授权终结点完成身份验证后，会将包含授权 code 的响应返回 Azure AD B2C。 Azure AD B2C 通过将 POST 请求发送到标识提供者的 /token 终结点，来兑换访问令牌的授权代码。本部分介绍令牌终结点元数据，该元数据允许配置对标识提供者的 /token 终结点的请求。

以下 HTTP 请求显示对标识提供者的令牌终结点的 Azure AD B2C 调用。

POST https://contoso/oauth2/token 
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=12345&scope=profile offline_access&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...

下表列出了令牌终结点元数据。

特性	必选	说明
`AccessTokenEndpoint`	是	令牌终结点的 URL。例如，`https://www.linkedin.com/oauth/v2/accessToken`。
`HttpBinding`	否	对令牌终结点的预期 HTTP 绑定。可能的值：`GET` 或 `POST`。
`AccessTokenResponseFormat`	否	访问令牌终结点调用的格式。例如，Facebook 需要 HTTP GET 方法，但访问令牌响应采用 JSON 格式。可能的值：`Default`、`Json` 和 `JsonP`。
`ExtraParamsInAccessTokenEndpointResponse`	否	包含可在某些标识提供者的 AccessTokenEndpoint 响应中返回的附加参数。例如，AccessTokenEndpoint 的响应包含 `openid` 等附加参数，在 ClaimsEndpoint 请求查询字符串中，除 access_token 以外，此参数也是必需的参数。多个参数名称应该转义，并以逗号“,”分隔符分隔。
`token_endpoint_auth_method`	否	指定 Azure AD B2C 如何向令牌终结点发送身份验证标头。可能的值：`client_secret_post`（默认值）和 `client_secret_basic`、`private_key_jwt`。有关详细信息，请参阅 OpenID Connect 客户端身份验证部分。
`token_signing_algorithm`	否	指定 `token_endpoint_auth_method` 设置为 `private_key_jwt` 时要使用的签名算法。可能的值：`RS256`（默认值）或 `RS512`。

配置 HTTP 绑定方法

默认情况下，使用 HTTP POST 请求令牌终结点。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">POST</Item>

以下 HTTP 调用演示了如何使用 HTTP POST 请求调用令牌终结点：

POST /oauth2/token

client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

对于需要在 /token 终结点使用 HTTP GET 方法的标识提供者，请将 HttpBinding 元数据设置为 GET。请注意，在下面的示例中，将 AccessTokenResponseFormat 设置为了 json，因为令牌终结点以 JSON 格式返回响应。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">GET</Item>
<Item Key="AccessTokenResponseFormat">json</Item>

GET /oauth2/token?client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

配置访问令牌响应格式

对于支持 HTTP POST 方法的标识提供者，AccessTokenResponseFormat 默认设置为 json。如果标识提供者支持 HTTP GET 请求，则必须将访问令牌响应格式显式设置为 json。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">GET</Item>
<Item Key="AccessTokenResponseFormat">json</Item>

下面的示例演示了 JSON 格式的令牌终结点响应：

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...",
    "token_type": "Bearer",
    "not_before": 1637924390,
    "expires_in": 960000,
}

配置身份验证方法

请求令牌终结点始终需要进行身份验证。默认情况下，Azure AD B2C 为标识提供者提供客户端凭据。默认的身份验证方法为 client_secret_post，包括请求正文中的客户端凭据（client_id 和 client_secret）。

以下对令牌终结点的 HTTP 请求包含 POST 数据中的 client_id 和 client_secret。对于 GET 请求，client_id 和 client_secret 包含在查询字符串参数中。

POST /oauth2/token

client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

对于需要在其 /token 终结点使用 HTTP 基本身份验证的标识提供者，请将 token_endpoint_auth_method 元数据配置为 client_secret_basic。通过这种类型的身份验证方法，可使用 HTTP 基本身份验证方案将客户端凭据传递给标识提供者。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="token_endpoint_auth_method">client_secret_basic</Item>

以下 HTTP 请求演示了如何使用 HTTP 基本身份验证调用令牌终结点。授权标头包含客户端 ID 和客户端密码，格式为 base64 编码的 client_ID:client_secret。

POST /oauth2/token

Authorization: Basic YWJjZDoxMjM0

redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

对于支持私钥 JWT 身份验证的标识提供者，请将 token_endpoint_auth_method 元数据配置为 private_key_jwt。使用这种类型的身份验证方法时，提供给 Azure AD B2C 的证书将用于生成已签名的断言，该断言通过 client_assertion 参数传递给标识提供者。 client_assertion_type 设置为 urn:ietf:params:oauth:client-assertion-type:jwt-bearer。 token_signing_algorithm 元数据指定 JWT 令牌的签名算法。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="token_endpoint_auth_method">private_key_jwt</Item>
<Item Key="token_signing_algorithm">RS256</Item>

以下 HTTP 请求演示了如何使用私钥 JWT 身份验证调用令牌终结点。

POST /oauth2/token

client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjJFRFg0dWRYeDIxbXNoaXdJVzczMUY3OUZSbFJiUDZXVXJyZmktR1RFeVkifQ.eyJpc3MiOiJhYmNkIiwiZXhwIjoxNjM3OTI5ODY0LCJuYmYiOjE2Mzc5Mjk1NjQsImF1ZCI6Imh0dHBzOi8vNWRlNC0xMDktNjQtMTI0LTUzLm5ncm9rLmlvL2FjY2Vzc190b2tlbiIsImp0aSI6IjVxQWlGV2lEODNDbU1KWWNrejBRdGc9PSIsInN1YiI6ImFiY2QiLCJpYXQiOjE2Mzc5Mjk1NjR9.C4OtRnrLaQatpT5LP45O5Nb418S4v8yZi_C42ld440w&client_id=abcd&client_assertion_type=urn%3aietf%3aparams%3aoauth%3aclient-assertion-type%3ajwt-bearer&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

用户信息终结点元数据

Azure AD B2C 从 OAuth2 标识提供者获取访问令牌后，它将调用用户信息终结点。用户信息终结点（也称为声明终结点）旨在检索有关经过身份验证的用户的声明。 Azure AD B2C 使用持有者令牌身份验证向标识提供者用户信息终结点进行身份验证。持有者令牌是 Azure AD B2C 从标识提供者 /token 终结点获取的访问令牌。

对用户信息终结点的请求始终采用 HTTP GET。在名为 access_token 的查询字符串参数中发送访问令牌。以下 HTTP 请求显示了如何使用查询字符串参数中的访问令牌调用用户信息终结点。

GET /oauth2/claims?access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

下表列出了用户信息终结点元数据。

特性	必选	说明
`ClaimsEndpoint`	是	用户信息终结点的 URL。例如，`https://api.linkedin.com/v2/me`。
`ClaimsEndpointAccessTokenName`	否	访问令牌查询字符串参数的名称。默认值：`access_token`。
`ClaimsEndpointFormatName`	否	格式查询字符串参数的名称。例如，可在此 LinkedIn 声明终结点 `https://api.linkedin.com/v1/people/~?format=json` 中将名称设置为 `format`。
`ClaimsEndpointFormat`	否	格式查询字符串参数的值。例如，可在此 LinkedIn 声明终结点 `https://api.linkedin.com/v1/people/~?format=json` 中将值设置为 `json`。
`BearerTokenTransmissionMethod`	否	指定令牌的发送方式。默认方法为使用查询字符串。若要将令牌作为请求头发送，请将其设置为 `AuthorizationHeader`。
`ExtraParamsInClaimsEndpointRequest`	否	包含可在某些标识提供者的 ClaimsEndpoint 请求中返回的附加参数。多个参数名称应该转义，并以逗号“,”分隔符分隔。

配置访问令牌查询字符串参数

用户信息终结点可能要求在特定的查询字符串参数中发送访问令牌。若要更改包含访问令牌的查询字符串参数的名称，请使用 ClaimsEndpointAccessTokenName 元数据。在下面的示例中，访问令牌查询字符串参数设置为 token。

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="ClaimsEndpointAccessTokenName">token</Item>

以下 HTTP 调用演示了如何通过将 ClaimsEndpointAccessTokenName 设置为 token 来调用用户信息终结点：

GET /oauth2/claims?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

配置声明格式

通过 ClaimsEndpointFormatName 和 ClaimsEndpointFormat 可向用户信息终结点发送一个键值对查询字符串参数。下面的示例配置名为 format 的查询字符串参数，其值为 json。

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="ClaimsEndpointFormatName">format</Item>
<Item Key="ClaimsEndpointFormat">json</Item>

以下 HTTP 请求演示了如何通过配置 ClaimsEndpointFormatName 和 ClaimsEndpointFormat 来调用用户信息终结点。

GET /oauth2/claims?format=json&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

配置持有者令牌传输方法

默认情况下，通过查询字符串参数将访问令牌发送到标识提供者用户信息终结点。若要在 HTTP Authorization 标头中发送令牌，请将 BearerTokenTransmissionMethod 元数据设置为 AuthorizationHeader。

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="BearerTokenTransmissionMethod">AuthorizationHeader</Item>

以下 HTTP 请求演示了将 BearerTokenTransmissionMethod 设置为 AuthorizationHeader 时如何传递访问令牌。

GET /oauth2/claims

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

传递令牌终结点返回的参数

某些标识提供者要求将从令牌终结点返回的额外参数传递到用户信息终结点。例如，来自令牌终结点的响应包含一个名为 resource 的参数，该参数是用户信息终结点的必需参数（访问令牌除外）。使用 ExtraParamsInClaimsEndpointRequest 元数据指定要传递的任何额外参数。多个参数名称应该转义，并以逗号“,”分隔符分隔。

下面的 JSON 演示了带有 resource 参数的令牌终结点返回的 JSON 有效负载。

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...",
    "token_type": "Bearer",
    "not_before": 1549647431,
    "expires_in": 960000,
    "resource": "f2a76e08-93f2-4350-833c-965c02483b11"
}

若要将 resource 参数传递给用户信息终结点，请添加以下元数据：

<Item Key="ExtraParamsInClaimsEndpointRequest">resource</Item>

以下 HTTP 请求演示如何将 resource 参数传递给用户信息终结点。

GET /oauth2/claims?resource=f2a76e08-93f2-4350-833c-965c02483b11&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

结束会话终结点

若要将用户从应用程序注销，请将用户重定向到 Azure AD B2C 注销终结点（对于 OAuth2 和 OpenID Connect）或发送 LogoutRequest（对于 SAML）。 Azure AD B2C 将从浏览器中清除用户的会话。收到注销请求后，Azure AD B2C 会尝试从用户可能通过其登录的所有联合标识提供者处进行注销。 OAuth2 标识提供者的注销 URI 是在 end_session_endpoint 元数据中进行配置。如果用户通过 Azure AD B2C 注销应用程序，将创建一个隐藏的 iframe，它将在其 Azure AD B2C 注销页中调用 end_session_endpoint。