In Azure AD B2C, you can define the business logic that users follow to gain access to your application. For example, you can determine the sequence of steps users follow when they sign in, sign up, edit a profile, or reset a password. After completing the sequence, the user acquires a token and gains access to your application.

In Azure AD B2C, there are two ways to provide identity user experiences:

• User flows are predefined, built-in, configurable policies that are provided so you can create sign-up, sign-in, and policy editing experiences in minutes.
• Custom policies enable you to create your own user journeys for complex identity experience scenarios.

The following screenshot shows the user flow settings UI, versus custom policy configuration files.

User flows

To set up the most common identity tasks, the Azure portal includes several predefined and configurable policies called user flows.

You can configure user flow settings like these to control identity experience behaviour’s in your applications:

• Account types used for sign-in, such as social accounts like Facebook, or local accounts that use an email address and password for sign-in
• Attributes to be collected from the consumer, such as first name, postal code, or country/region of residency
• Azure AD Multi-Factor Authentication (MFA)
• Customization of the user interface
• Set of claims in a token that your application receives after the user completes the user flow
• Session management
• ...and more

Most of the common identity scenarios for apps can be defined and implemented effectively with user flows. We recommend that you use the built-in user flows, unless you have complex user journey scenarios that require the full flexibility of custom policies.

Custom policies

Custom policies are configuration files that define the behaviour of your Azure AD B2C tenant user experience. While user flows are predefined in the Azure AD B2C portal for the most common identity tasks, custom policies can be fully edited by an identity developer to complete many different tasks.

A custom policy is fully configurable and policy-driven. It orchestrates trust between entities in standard protocols.

For Examples, OpenID Connect, OAuth, SAML, and a few non-standard ones, for example, REST API-based system-to-system claims exchanges. The framework creates user-friendly, white-labelled experiences.

The custom policy gives you the ability to construct user journeys with any combination of steps. For example:

• Federate with other identity providers
• First- and third-party multifactor authentication (MFA) challenges
• Collect any user input
• Integrate with external systems using REST API communication

Below shows each user journey is defined by a policy.

You can build as many or as few policies as you need to enable the best user experience for your organization.

A custom policy is defined by several XML files that refer to each other in a hierarchical chain. The XML elements define the claims schema, claims transformations, content definitions, claims providers, technical profiles, user journey orchestration steps, and other aspects of the identity experience.

The powerful flexibility of custom policies is most appropriate for when you need to build complex identity scenarios. Developers configuring custom policies must define the trusted relationships in careful detail to include metadata endpoints, exact claims exchange definitions, and configure secrets, keys, and certificates as needed by each identity provider.

Learn more about custom policies in Custom policies in Azure Active Directory B2C.

Comparing user flows and custom policies

 

The following table gives a detailed comparison of the scenarios you can enable with Azure AD B2C user flows and custom policies.

Application integration

You can create many user flows, or custom policies of different types in your tenant and use them in your applications as needed. Both user flows and custom policies can be reused across applications. This flexibility enables you to define and modify identity experiences with minimal or no changes to your code.

• When a user wants to sign into your application, the application initiates an authorization request to a user flow- or custom policy-provided endpoint.
• The user flow or custom policy defines and controls the user's experience.
• When they complete a user flow, Azure AD B2C generates a token, then redirects the user back to your application.

 

Multiple applications can use the same user flow or custom policy. A single application can use multiple user flows or custom policies.

For example, to sign into an application, the application uses the sign up or sign in user flow. After the user has signed in, they may want to edit their profile. To edit the profile, the application initiates another authorization request, this time using the profile edit user flow.

Your application triggers a user flow by using a standard HTTP authentication request that includes the user flow or custom policy name. A customized token is received as a response.

 

Azure AD B2C custom policy overview

Custom policies are configuration files that define the behaviour of your Azure Active Directory B2C (Azure AD B2C) tenant. While user flows are predefined in the Azure AD B2C portal for the most common identity tasks, custom policies can be fully edited by an identity developer to complete many different tasks.

A custom policy is fully configurable and policy-driven. A custom policy orchestrates trust between entities in standard protocols. For example, OpenID Connect, OAuth, SAML, and a few non-standard ones, for example, REST API-based system-to-system claims exchanges. The framework creates user-friendly, white-labelled experiences.

A custom policy is represented as one or more XML-formatted files, which refer to each other in a hierarchical chain. The XML elements define the building blocks, the interaction with the user, and other parties, and the business logic.

Custom policy starter pack

Azure AD B2C custom policy starter pack comes with several pre-built policies to get you going quickly. Each of these starter packs contains the smallest number of technical profiles and user journeys needed to achieve the scenarios described:

• LocalAccounts- Enables the use of local accounts only.
• SocialAccounts- Enables the use of social (or federated) accounts only.
• SocialAndLocalAccounts- Enables the use of both local and social accounts. Most of our samples refer to this policy.
• SocialAndLocalAccountsWithMFA- Enables social, local, and multi-factor authentication options.

In the Azure AD B2C samples GitHub repository, you'll find samples for several enhanced Azure AD B2C custom CIAM user journeys. For example, local account policy enhancements, social account policy enhancements, MFA enhancements, user interface enhancements, generic enhancements, app migration, user migration, conditional access, web test, and CI/CD.

 

Understanding the basics

Claims

A claim provides temporary storage of data during an Azure AD B2C policy execution. It can store information about the user, such as first name, last name, or any other claim obtained from the user or other systems (claims exchanges). The claims schema is the place where you declare your claims.

When the policy runs, Azure AD B2C sends and receives claims to and from internal and external parties and then sends a subset of these claims to your relying party application as part of the token. Claims are used in these ways:

• A claim is saved, read, or updated against the directory user object.
• A claim is received from an external identity provider.
• Claims are sent or received using a custom REST API service.
• Data is collected as claims from the user during the sign-up or edit profile flows.

Manipulating your claims

The claims transformations are predefined functions that can be used to convert a given claim into another one, evaluate a claim, or set a claim value. For example adding an item to a string collection, changing the case of a string, or evaluate a date and time claim. A claims transformation specifies a transform method.

Customize and localize your UI

To collect information from your users by presenting a page in their web browser, use the self-asserted technical profile. You can edit your self-asserted technical profile to add claims and customize user input.

To customize the user interface for your self-asserted technical profile, you specify a URL in the content definition element with customized HTML content. In the self-asserted technical profile, you point to this content definition ID.

To customize language-specific strings, use the localization element. A content definition may contain a localization reference that specifies a list of localized resources to load. Azure AD B2C merges user interface elements with the HTML content that's loaded from your URL and then displays the page to the user.

 

Relying party policy overview

A relying party application, which in the SAML protocol is known as a service provider, calls the relying party policy to execute a specific user journey. The relying party policy specifies the user journey to be executed, and list of claims that the token includes.

All relying party applications that use the same policy will receive the same token claims, and the user goes through the same user journey.

User Journeys

User journeys allows you to define the business logic with path through which user will follow to gain access to your application. The user is taken through the user journey to retrieve the claims that are to be presented to your application. A user journey is built from a sequence of orchestration steps. A user must reach the last step to acquire a token.

The following instructions describe how you can add orchestration steps to the social and local account starter pack policy. Here's an example of a REST API call that has been added.

Orchestration steps

The orchestration step references to a method that implements its intended purpose or functionality. This method is called a technical profile. When your user journey needs branching to better represent the business logic, the orchestration step references to sub journey. A sub journey contains its own set of orchestration steps.

A user must reach the last orchestration step in the user journey to acquire a token. But users may not need to travel through all of the orchestration steps. Orchestration steps can be conditionally executed based on preconditions defined in the orchestration step.

After an orchestration step completes, Azure AD B2C stores the outputted claims in the claims bag. The claims in the claims bag can be utilized by any further orchestration steps in the user journey.

The following diagram shows how the user journey's orchestration steps can access the claims bag.

 

 

Technical profile

A technical profile provides an interface to communicate with different types of parties. A user journey combines calling technical profiles via orchestration steps to define your business logic.

All types of technical profiles share the same concept. You send input claims, run claims transformation, and communicate with the configured party. After the process is completed, the technical profile returns the output claims to claims bag. For more information, see technical profiles overview.

Validation technical profile

When a user interacts with the user interface, you may want to validate the data that is collected. To interact with the user, a self-asserted technical profile must be used.

To validate the user input, a validation technical profile is called from the self-asserted technical profile. A validation technical profile is a method to call any non-interactive technical profile. In this case, the technical profile can return output claims, or an error message. The error message is rendered to the user on-screen, allowing the user to retry.

The following diagram illustrates how Azure AD B2C uses a validation technical profile to validate the user credentials.

Inheritance model

Each starter pack includes the following files:

• A Base file that contains most of the definitions. To help with troubleshooting and long-term maintenance of your policies, try to minimize the number of changes you make to this file.
• A Localization file that holds the localization strings. This policy file is derived from the Base file. Use this file to accommodate different languages to suit your customer needs.
• An Extensionsfile that holds the unique configuration changes for your tenant. This policy file is derived from the Localization file. Use this file to add new functionality or override existing functionality. For example, use this file to federate with new identity providers.
• A Relying Party (RP) file that is the single task-focused file that is invoked directly by the relying party application, such as your web, mobile, or desktop applications. Each unique task, such as sign-up, sign-in, or profile edit, requires its own relying party policy file. This policy file is derived from the extensions file.

 

The inheritance model is as follows:

• The child policy at any level can inherit from the parent policy and extend it by adding new elements.
• For more complex scenarios, you can add more inheritance levels (up to 10 in total).
• You can add more relying party policies. For example, delete my account, change a phone number, SAML relying party policy and more.

The following diagram shows the relationship between the policy files and the relying party applications.

Ref URL’s
https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack
https://github.com/azure-ad-b2c/samples

Guidance

Best practices

Within an Azure AD B2C custom policy, you can integrate your own business logic to build the user experiences you require and extend functionality of the service. We have a set of best practices and recommendations to get started.

• Create your logic within the extension policy or relying party policy. You can add new elements, which will override the base policy by referencing the same ID. This approach will allow you to scale out your project while making it easier to upgrade the base policy later on if Microsoft releases new starter packs.
  
  
• Within the base policy, we highly recommend avoiding making any changes. When necessary, make comments where the changes are made.
  
  
• When you're overriding an element, such as technical profile metadata, avoid copying the entire technical profile from the base policy. Instead, copy only the required section of the element. See Disable email verificationfor an example of how to make the change.
  
  
• To reduce duplication of technical profiles, where core functionality is shared, use technical profile inclusion.
  
  
• Avoid writing to the Azure AD directory during sign-in, which may lead to throttling issues.
  
  
• If your policy has external dependencies, such as REST APIs, makes sure they're highly available.
  
  
• For a better user experience, make sure your custom HTML templates, are globally deployed using online content delivery. Azure Content Delivery Network (CDN) lets you reduce load times, save bandwidth, and improve response speed.
  
  
• If you want to make a change to user journey, copy the entire user journey from the base policy to the extension policy. Provide a unique user journey ID to the user journey you've copied. Then in the relying party policy, change the default user journeyelement to point to the new user journey.