Define an OAuth2 technical profile in an Azure Active Directory B2C custom policy

Note

In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. For most scenarios, we recommend that you use built-in user flows. If you've not done so, learn about custom policy starter pack in Get started with custom policies in Active Directory B2C.

Azure Active Directory B2C (Azure AD B2C) provides support for the OAuth2 protocol identity provider. OAuth2 is the primary protocol for authorization and delegated authentication. For more information, see the RFC 6749 The OAuth 2.0 Authorization Framework. With an OAuth2 technical profile, you can federate with an OAuth2 based identity provider, such as Facebook. Federating with an identity provider allows users to sign in with their existing social or enterprise identities.

Protocol

The Name attribute of the Protocol element needs to be set to OAuth2. For example, the protocol for the Facebook-OAUTH technical profile is OAuth2:

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

Input claims

The InputClaims and InputClaimsTransformations elements are not required. But you may want to send additional parameters to your identity provider. The following example adds the domain_hint query string parameter with the value of contoso.com to the authorization request.

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

Output claims

The OutputClaims element contains a list of claims returned by the OAuth2 identity provider. You may need to map the name of the claim defined in your policy to the name defined in the identity provider. You can also include claims that aren't returned by the identity provider as long as you set the DefaultValue attribute.

The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.

The following example shows the claims returned by the Facebook identity provider:

  • The first_name claim is mapped to the givenName claim.
  • The last_name claim is mapped to the surname claim.
  • The displayName claim without name-mapping.
  • The email claim without name mapping.

The technical profile also returns claims that aren't returned by the identity provider:

  • The identityProvider claim that contains the name of the identity provider.
  • The authenticationSource claim with a default value of 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>

Metadata

Attribute Required Description
client_id Yes The application identifier of the identity provider.
IdTokenAudience No The audience of the id_token. If specified, Azure AD B2C checks whether the token is in a claim returned by the identity provider and is equal to the one specified.
authorization_endpoint Yes The URL of the authorization endpoint as per RFC 6749.
AccessTokenEndpoint Yes The URL of the token endpoint as per RFC 6749.
ClaimsEndpoint Yes The URL of the user information endpoint as per RFC 6749.
end_session_endpoint Yes The URL of the end session endpoint as per RFC 6749.
AccessTokenResponseFormat No The format of the access token endpoint call. For example, Facebook requires an HTTP GET method, but the access token response is in JSON format.
AdditionalRequestQueryParameters No Additional request query parameters. For example, you may want to send additional parameters to your identity provider. You can include multiple parameters using comma delimiter.
ClaimsEndpointAccessTokenName No The name of the access token query string parameter. Some identity providers' claims endpoints support GET HTTP request. In this case, the bearer token is sent by using a query string parameter instead of the authorization header. Default value: access_token.
ClaimsEndpointFormatName No The name of the format query string parameter. For example, you can set the name as format in this LinkedIn claims endpoint https://api.linkedin.com/v1/people/~?format=json.
ClaimsEndpointFormat No The value of the format query string parameter. For example, you can set the value as json in this LinkedIn claims endpoint https://api.linkedin.com/v1/people/~?format=json.
BearerTokenTransmissionMethod No Specifies how the token is sent. The default method is a query string. To send the token as a request header, set to AuthorizationHeader.
ProviderName No The name of the identity provider.
response_mode No The method that the identity provider uses to send the result back to Azure AD B2C. Possible values: query, form_post (default), or fragment.
scope No The scope of the request that is defined according to the OAuth2 identity provider specification. Such as openid, profile, and email.
HttpBinding No The expected HTTP binding to the access token and claims token endpoints. Possible values: GET or POST.
ResponseErrorCodeParamName No The name of the parameter that contains the error message returned over HTTP 200 (Ok).
ExtraParamsInAccessTokenEndpointResponse No Contains the extra parameters that can be returned in the response from AccessTokenEndpoint by some identity providers. For example, the response from AccessTokenEndpoint contains an extra parameter such as openid, which is a mandatory parameter besides the access_token in a ClaimsEndpoint request query string. Multiple parameter names should be escaped and separated by the comma ',' delimiter.
ExtraParamsInClaimsEndpointRequest No Contains the extra parameters that can be returned in the ClaimsEndpoint request by some identity providers. Multiple parameter names should be escaped and separated by the comma ',' delimiter.
IncludeClaimResolvingInClaimsHandling   No For input and output claims, specifies whether claims resolution is included in the technical profile. Possible values: true, or false (default). If you want to use a claims resolver in the technical profile, set this to true.
ResolveJsonPathsInJsonTokens No Indicates whether the technical profile resolves JSON paths. Possible values: true, or false (default). Use this metadata to read data from a nested JSON element. In an OutputClaim, set the PartnerClaimType to the JSON path element you want to output. For example: firstName.localized, or data.0.to.0.email.
token_endpoint_auth_method No Specifies how Azure AD B2C sends the authentication header to the token endpoint. Possible values: client_secret_post (default), and client_secret_basic (public preview), private_key_jwt (public preview). For more information, see OpenID Connect client authentication section.
token_signing_algorithm No Specifies the signing algorithm to use when token_endpoint_auth_method is set to private_key_jwt. Possible values: RS256 (default) or RS512.
SingleLogoutEnabled No Indicates whether during sign-in the technical profile attempts to sign out from federated identity providers. For more information, see Azure AD B2C session sign-out. Possible values: true (default), or false.
UsePolicyInRedirectUri No Indicates whether to use a policy when constructing the redirect URI. When you configure your application in the identity provider, you need to specify the redirect URI. The redirect URI points to Azure AD B2C, https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/oauth2/authresp. If you specify true, you need to add a redirect URI for each policy you use. For example: https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/{policy-name}/oauth2/authresp.

Cryptographic keys

The CryptographicKeys element contains the following attribute:

Attribute Required Description
client_secret Yes The client secret of the identity provider application. The cryptographic key is required only if the response_types metadata is set to code. In this case, Azure AD B2C makes another call to exchange the authorization code for an access token. If the metadata is set to id_token, you can omit the cryptographic key.

Redirect URI

When you configure the redirect URI of your identity provider, enter https://{tenant-name}.b2clogin.com/{tenant-name}.onmicrosoft.com/oauth2/authresp. Make sure to replace {tenant-name} with your tenant's name (for example, contosob2c). The redirect URI needs to be in all lowercase.

Examples: