RelyingParty

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.

The RelyingParty element specifies the user journey to enforce for the current request to Azure Active Directory B2C (Azure AD B2C). It also specifies the list of claims that the relying party (RP) application needs as part of the issued token. An RP application, such as a web, mobile, or desktop application, calls the RP policy file. The RP policy file executes a specific task, such as signing in, resetting a password, or editing a profile. Multiple applications can use the same RP policy and a single application can use multiple policies. All RP applications receive the same token with claims, and the user goes through the same user journey.

The following example shows a RelyingParty element in the B2C_1A_signup_signin policy file:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TrustFrameworkPolicy
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="https://www.w3.org/2001/XMLSchema"
  xmlns="http://schemas.microsoft.com/online/cpim/schemas/2013/06"
  PolicySchemaVersion="0.3.0.0"
  TenantId="your-tenant.onmicrosoft.com"
  PolicyId="B2C_1A_signup_signin"
  PublicPolicyUri="http://your-tenant.onmicrosoft.com/B2C_1A_signup_signin">

  <BasePolicy>
    <TenantId>your-tenant.onmicrosoft.com</TenantId>
    <PolicyId>B2C_1A_TrustFrameworkExtensions</PolicyId>
  </BasePolicy>

  <RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <UserJourneyBehaviors>
      <SingleSignOn Scope="Tenant" KeepAliveInDays="7"/>
      <SessionExpiryType>Rolling</SessionExpiryType>
      <SessionExpiryInSeconds>900</SessionExpiryInSeconds>
      <JourneyInsights TelemetryEngine="ApplicationInsights" InstrumentationKey="your-application-insights-key" DeveloperMode="true" ClientEnabled="false" ServerEnabled="true" TelemetryVersion="1.0.0" />
      <ContentDefinitionParameters>
        <Parameter Name="campaignId">{OAUTH-KV:campaignId}</Parameter>
      </ContentDefinitionParameters>
    </UserJourneyBehaviors>
    <TechnicalProfile Id="PolicyProfile">
      <DisplayName>PolicyProfile</DisplayName>
      <Description>The policy profile</Description>
      <Protocol Name="OpenIdConnect" />
      <Metadata>collection of key/value pairs of data</Metadata>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="displayName" />
        <OutputClaim ClaimTypeReferenceId="givenName" />
        <OutputClaim ClaimTypeReferenceId="surname" />
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
        <OutputClaim ClaimTypeReferenceId="identityProvider" />
        <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>
  ...

The optional RelyingParty element contains the following elements:

Element	Occurrences	Description
DefaultUserJourney	1:1	The default user journey for the RP application.
Endpoints	0:1	A list of endpoints. For more information, see UserInfo endpoint.
UserJourneyBehaviors	0:1	The scope of the user journey behaviors.
TechnicalProfile	1:1	A technical profile that's supported by the RP application. The technical profile provides a contract for the RP application to contact Azure AD B2C.

You need to create the RelyingParty child elements in the order presented in the preceding table.

Endpoints

The Endpoints element contains the following element:

Element	Occurrences	Description
Endpoint	1:1	A reference to an endpoint.

The Endpoint element contains the following attributes:

Attribute	Required	Description
Id	Yes	A unique identifier of the endpoint.
UserJourneyReferenceId	Yes	An identifier of the user journey in the policy. For more information, see user journeys

The following example shows a relying party with UserInfo endpoint:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <Endpoints>
    <Endpoint Id="UserInfo" UserJourneyReferenceId="UserInfoJourney" />
  </Endpoints>
  ...

DefaultUserJourney

The DefaultUserJourney element specifies a reference to the identifier of the user journey that is defined in the Base or Extensions policy. The following examples show the sign-up or sign-in user journey specified in the RelyingParty element:

B2C_1A_signup_signin policy:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn">
  ...

B2C_1A_TrustFrameWorkBase or B2C_1A_TrustFrameworkExtensionPolicy:

<UserJourneys>
  <UserJourney Id="SignUpOrSignIn">
  ...

The DefaultUserJourney element contains the following attribute:

Attribute	Required	Description
ReferenceId	Yes	An identifier of the user journey in the policy. For more information, see user journeys

UserJourneyBehaviors

The UserJourneyBehaviors element contains the following elements:

Element	Occurrences	Description
SingleSignOn	0:1	The scope of the single sign-on (SSO) session behavior of a user journey.
SessionExpiryType	0:1	The authentication behavior of the session. Possible values: Rolling or Absolute. The Rolling value (default) indicates that the user remains signed in as long as the user is continually active in the application. The Absolute value indicates that the user is forced to reauthenticate after the time period specified by application session lifetime.
SessionExpiryInSeconds	0:1	The lifetime of Azure AD B2C's session cookie specified as an integer stored on the user's browser upon successful authentication. The default is 86,400 seconds (24 hours). The minimum is 900 seconds (15 minutes). The maximum is 86,400 seconds (24 hours).
JourneyInsights	0:1	The Azure Application Insights instrumentation key to be used.
ContentDefinitionParameters	0:1	The list of key value pairs to be appended to the content definition load URI.
JourneyFraming	0:1	Allows the user interface of this policy to be loaded in an iframe.
ScriptExecution	0:1	The supported JavaScript execution modes. Possible values: Allow or Disallow (default).

When you use the above elements, you need add them to your UserJourneyBehaviors element in the order specified in the table. For example, the JourneyInsights element must be added before (above) the ScriptExecution element.

SingleSignOn

The SingleSignOn element contains the following attributes:

Attribute	Required	Description
Scope	Yes	The scope of the single sign-on behavior. Possible values: Suppressed, Tenant, Application, or Policy. The Suppressed value indicates that the behavior is suppressed, and the user is always prompted for an identity provider selection. The Tenant value indicates that the behavior is applied to all policies in the tenant. For example, a user navigating through two policy journeys for a tenant is not prompted for an identity provider selection. The Application value indicates that the behavior is applied to all policies for the application making the request. For example, a user navigating through two policy journeys for an application is not prompted for an identity provider selection. The Policy value indicates that the behavior only applies to a policy. For example, a user navigating through two policy journeys for a trust framework is prompted for an identity provider selection when switching between policies.
KeepAliveInDays	No	Controls how long the user remains signed in. Setting the value to 0 turns off KMSI functionality. The default is 0 (disabled). The minimum is 1 day. The maximum is 90 days. For more information, see Keep me signed in.
EnforceIdTokenHintOnLogout	No	Force to pass a previously issued ID token to the logout endpoint as a hint about the end user's current authenticated session with the client. Possible values: false (default), or true. For more information, see Web sign-in with OpenID Connect.

JourneyInsights

The JourneyInsights element contains the following attributes:

Attribute	Required	Description
TelemetryEngine	Yes	The value must be ApplicationInsights.
InstrumentationKey	Yes	The string that contains the instrumentation key for the application insights element.
DeveloperMode	Yes	Possible values: true or false. If true, Application Insights expedites the telemetry through the processing pipeline. This setting is good for development, but constrained at high volumes. The detailed activity logs are designed only to aid in development of custom policies. Do not use development mode in production. Logs collect all claims sent to and from the identity providers during development. If used in production, the developer assumes responsibility for personal data collected in the App Insights log that they own. These detailed logs are only collected when this value is set to true.
ClientEnabled	Yes	Possible values: true or false. If true, sends the Application Insights client-side script for tracking page view and client-side errors.
ServerEnabled	Yes	Possible values: true or false. If true, sends the existing UserJourneyRecorder JSON as a custom event to Application Insights.
TelemetryVersion	Yes	The value must be 1.0.0.

For more information, see Collecting Logs

ContentDefinitionParameters

By using custom policies in Azure AD B2C, you can send a parameter in a query string. By passing the parameter to your HTML endpoint, you can dynamically change the page content. For example, you can change the background image on the Azure AD B2C sign-up or sign-in page, based on a parameter that you pass from your web or mobile application. Azure AD B2C passes the query string parameters to your dynamic HTML file, such as aspx file.

The following example passes a parameter named campaignId with a value of hawaii in the query string:

https://login.microsoft.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?pB2C_1A_signup_signin&client_id=00001111-aaaa-2222-bbbb-3333cccc4444&nonce=defaultNonce&redirect_uri=http%3A%2F%2Fjwt.io%2F&scope=openid&response_type=id_token&prompt=login&campaignId=hawaii

The ContentDefinitionParameters element contains the following element:

Element	Occurrences	Description
ContentDefinitionParameter	0:n	A string that contains the key value pair that's appended to the query string of a content definition load URI.

The ContentDefinitionParameter element contains the following attribute:

Attribute	Required	Description
Name	Yes	The name of the key value pair.

For more information, see Configure the UI with dynamic content by using custom policies

JourneyFraming

The JourneyFraming element contains the following attributes:

Attribute	Required	Description
Enabled	Yes	Enables this policy to be loaded within an iframe. Possible values: false (default), or true.
Sources	Yes	Contains the domains that will load host the iframe. For more information, see Loading Azure B2C in an iframe.

TechnicalProfile

The TechnicalProfile element contains the following attribute:

Attribute	Required	Description
Id	Yes	The value must be PolicyProfile.

The TechnicalProfile contains the following elements:

Element	Occurrences	Description
DisplayName	1:1	The string that contains the name of the technical profile.
Description	0:1	The string that contains the description of the technical profile.
Protocol	1:1	The protocol used for the federation.
Metadata	0:1	The collection of Item of key/value pairs utilized by the protocol for communicating with the endpoint in the course of a transaction to configure interaction between the relying party and other community participants.
InputClaims	1:1	A list of claim types that are taken as input in the technical profile. Each of these elements contains reference to a ClaimType already defined in the ClaimsSchema section or in a policy from which this policy file inherits.
OutputClaims	1:1	A list of claim types that are taken as output in the technical profile. Each of these elements contains reference to a ClaimType already defined in the ClaimsSchema section or in a policy from which this policy file inherits.
SubjectNamingInfo	1:1	The subject name used in tokens.

The Protocol element contains the following attribute:

Attribute	Required	Description
Name	Yes	The name of a valid protocol supported by Azure AD B2C that is used as part of the technical profile. Possible values: OpenIdConnect or SAML2. The OpenIdConnect value represents the OpenID Connect 1.0 protocol standard as per OpenID foundation specification. The SAML2 represents the SAML 2.0 protocol standard as per OASIS specification.

Metadata

When the protocol is SAML, a metadata element contains the following elements. For more information, see Options for registering a SAML application in Azure AD B2C.

Attribute	Required	Description
IdpInitiatedProfileEnabled	No	Indicates whether the IDP initiated flow is supported. Possible values: true or false (default).
XmlSignatureAlgorithm	No	The method that Azure AD B2C uses to sign the SAML Response. Possible values: Sha256, Sha384, Sha512, or Sha1. Make sure you configure the signature algorithm on both sides with same value. Use only the algorithm that your certificate supports. To configure the SAML Assertion, see SAML issuer technical profile metadata.
DataEncryptionMethod	No	Indicates the method that Azure AD B2C uses to encrypt the data, using Advanced Encryption Standard (AES) algorithm. The metadata controls the value of the <EncryptedData> element in the SAML response. Possible values: Aes256 (default), Aes192, Sha512, or Aes128.
KeyEncryptionMethod	No	Indicates the method that Azure AD B2C uses to encrypt the copy of the key that was used to encrypt the data. The metadata controls the value of the <EncryptedKey> element in the SAML response. Possible values: Rsa15 (default) - RSA Public Key Cryptography Standard (PKCS) Version 1.5 algorithm, RsaOaep - RSA Optimal Asymmetric Encryption Padding (OAEP) encryption algorithm.
UseDetachedKeys	No	Possible values: true, or false (default). When the value is set to true, Azure AD B2C changes the format of the encrypted assertions. Using detached keys adds the encrypted assertion as a child of the EncrytedAssertion as opposed to the EncryptedData.
WantsSignedResponses	No	Indicates whether Azure AD B2C signs the Response section of the SAML response. Possible values: true (default) or false.
RemoveMillisecondsFromDateTime	No	Indicates whether the milliseconds will be removed from datetime values within the SAML response (these include IssueInstant, NotBefore, NotOnOrAfter, and AuthnInstant). Possible values: false (default) or true.
RequestContextMaximumLengthInBytes	No	Indicates the maximum length of the SAML applications RelayState parameter. The default is 1000. The maximum is 2048.

InputClaims

The InputClaims element contains the following element:

Element	Occurrences	Description
InputClaim	0:n	An expected input claim type.

The InputClaim element contains the following attributes:

Attribute	Required	Description
ClaimTypeReferenceId	Yes	A reference to a ClaimType already defined in the ClaimsSchema section in the policy file.
DefaultValue	No	A default value that can be used if the claim value is empty.
PartnerClaimType	No	Sends the claim in a different name as configured in the ClaimType definition.

OutputClaims

The OutputClaims element contains the following element:

Element	Occurrences	Description
OutputClaim	0:n	The name of an expected claim type in the supported list for the policy to which the relying party subscribes. This claim serves as an output for the technical profile.

The OutputClaim element contains the following attributes:

Attribute	Required	Description
ClaimTypeReferenceId	Yes	A reference to a ClaimType already defined in the ClaimsSchema section in the policy file.
DefaultValue	No	A default value that can be used if the claim value is empty.
PartnerClaimType	No	Sends the claim in a different name as configured in the ClaimType definition.

SubjectNamingInfo

With the SubjectNamingInfo element, you control the value of the token subject:

• JWT token - the sub claim. This is a principal about which the token asserts information, such as the user of an application. This value is immutable and cannot be reassigned or reused. It can be used to perform safe authorization checks, such as when the token is used to access a resource. By default, the subject claim is populated with the object ID of the user in the directory. For more information, see Token, session and single sign-on configuration.
• SAML token - the <Subject><NameID> element, which identifies the subject element. The NameId format can be modified.

The SubjectNamingInfo element contains the following attribute:

Attribute	Required	Description
ClaimType	Yes	A reference to an output claim's PartnerClaimType. The output claims must be defined in the relying party policy OutputClaims collection with a PartnerClaimType. For example, <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub" />, or <OutputClaim ClaimTypeReferenceId="signInName" PartnerClaimType="signInName" />.
Format	No	Used for SAML Relying parties to set the NameId format returned in the SAML Assertion.

The following example shows how to define an OpenID Connect relying party. The subject name info is configured as the objectId:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

The JWT token includes the sub claim with the user objectId:

{
  ...
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  ...
}

The following example shows how to define a SAML relying party. The subject name info is configured as the objectId, and the NameId format has been provided:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="SAML2" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/>
  </TechnicalProfile>
</RelyingParty>