Tutorial: Create user flows and custom policies in Azure Active Directory B2C

A user flow lets you determine how users interact with your application when they do things like sign-in, sign-up, edit a profile, or reset a password. In this article, you learn how to:

Custom policies are configuration files that define the behavior of your Azure Active Directory B2C (Azure AD B2C) tenant. In this article, you learn how to:

• If you don't have one already, create an Azure AD B2C tenant that is linked to your Azure subscription.
• Register a web application, and enable ID token implicit grant.

• If you don't have one already, create an Azure AD B2C tenant that is linked to your Azure subscription.
• Register a web application, and enable ID token implicit grant.

Create a sign-up and sign-in user flow

The sign-up and sign-in user flow handles both experiences with a single configuration. Users of your application are led down the right path depending on the context. To create a sign-up and sign-in user flow:

1. Sign in to the Azure portal.

2. If you have access to multiple tenants, select the Settings icon in the top menu to switch to your Azure AD B2C tenant from the Directories + subscriptions menu.

3. In the Azure portal, search for and select Azure AD B2C.

4. Under Policies, select User flows, and then select New user flow.

   

5. On the Create a user flow page, select the Sign up and sign in (Standard) user flow.

6. Enter a Name for the user flow. For example, signupsignin1.

7. For Identity providers, select your identity providers.

8. For User attributes and token claims, choose the claims and attributes that you want to collect and send from the user during sign-up. For example, select Show more, and then choose attributes and claims for Country/Region, Display Name, and Postal Code. Select OK.

   

9. Select Create to add the user flow. A prefix of B2C_1_ is automatically prepended to the name you entered earlier. For example, B2C_1_signupsignin1.

Test the user flow

1. From the User flows page, select the user flow you just created to open its overview page.

2. At the top of the user flow overview page, select Run user flow. A pane will open at the right side of the page.

3. For Application, select the web application you wish to test, such as the one named webapp1. The Reply URL should show https://jwt.ms.

4. Select Run user flow, and then select Sign up now.

   

5. Enter a valid email address, select Send verification code, enter the verification code that you receive, then select Verify code.

6. Enter a new password and confirm the password.

7. Select your country and region, enter the name that you want displayed, enter a postal code, and then select Create. The token is returned to https://jwt.ms and should be displayed to you in your browser.

8. You can now run the user flow again and you should be able to sign in with the account that you just created. The returned token includes the claims that you selected of country/region, name, and postal code.

Create a profile editing user flow

If you want to enable users to edit their profile in your application, you use a profile editing user flow.

1. In the menu of the Azure AD B2C tenant overview page, select User flows, and then select New user flow.
2. On the Create a user flow page, select the Profile editing (Standard) user flow.
3. Enter a Name for the user flow. For example, profileediting1.
4. For Identity providers, select your identity providers.
5. For User attributes, choose the attributes that you want the customer to be able to edit in their profile. For example, select Show more, and then choose both attributes and claims for Display name and Job title. Select OK.
6. Select Create to add the user flow. A prefix of B2C_1_ is automatically appended to the name.

Test the user flow

1. Select the user flow you created to open its overview page.
2. At the top of the user flow overview page, select Run user flow. A pane will open at the right side of the page.
3. For Application, select the web application you wish to test, such as the one named webapp1. The Reply URL should show https://jwt.ms.
4. Select Run user flow, and then sign in with the account that you previously created.
5. You now have the opportunity to change the display name and job title for the user. Select Continue. The token is returned to https://jwt.ms and should be displayed in your browser.

Add signing and encryption keys for Identity Experience Framework applications

1. Sign in to the Azure portal.
2. If you have access to multiple tenants, select the Settings icon in the top menu to switch to your Azure AD B2C tenant from the Directories + subscriptions menu.
3. In the Azure portal, search for and select Azure AD B2C.
4. On the overview page, under Policies, select Identity Experience Framework.

Create the signing key

1. Select Policy Keys and then select Add.
2. For Options, choose Generate.
3. In Name, enter TokenSigningKeyContainer. The prefix B2C_1A_ might be added automatically.
4. For Key type, select RSA.
5. For Key usage, select Signature.
6. Select Create.

Create the encryption key

1. Select Policy Keys and then select Add.
2. For Options, choose Generate.
3. In Name, enter TokenEncryptionKeyContainer. The prefix B2C_1A_ might be added automatically.
4. For Key type, select RSA.
5. For Key usage, select Encryption.
6. Select Create.

Register Identity Experience Framework applications

Azure AD B2C requires you to register two applications that it uses to sign up and sign in users with local accounts: IdentityExperienceFramework, a web API, and ProxyIdentityExperienceFramework, a native app with delegated permission to the IdentityExperienceFramework app. Your users can sign up with an email address or username and a password to access applications registered to your tenant, which creates a "local account." Local accounts exist only in your Azure AD B2C tenant.

You will need to register these two applications in your Azure AD B2C tenant only once.

Register the IdentityExperienceFramework application

To register an application in your Azure AD B2C tenant, you can use the App registrations experience.

1. Select App registrations, and then select New registration.
2. For Name, enter IdentityExperienceFramework.
3. Under Supported account types, select Accounts in this organizational directory only.
4. Under Redirect URI, select Web, and then enter https://your-tenant-name.b2clogin.cn/your-tenant-name.partner.onmschina.cn, where your-tenant-name is your Azure AD B2C tenant domain name.
5. Under Permissions, select the Grant admin consent to openid and offline_access permissions check box.
6. Select Register.
7. Record the Application (client) ID for use in a later step.

Next, expose the API by adding a scope:

1. In the left menu, under Manage, select Expose an API.
2. Select Add a scope, then select Save and continue to accept the default application ID URI.
3. Enter the following values to create a scope that allows custom policy execution in your Azure AD B2C tenant:
   • Scope name: user_impersonation
   • Admin consent display name: Access IdentityExperienceFramework
   • Admin consent description: Allow the application to access IdentityExperienceFramework on behalf of the signed-in user.
4. Select Add scope

---

Register the ProxyIdentityExperienceFramework application

1. Select App registrations, and then select New registration.
2. For Name, enter ProxyIdentityExperienceFramework.
3. Under Supported account types, select Accounts in this organizational directory only.
4. Under Redirect URI, use the drop-down to select Public client/native (mobile & desktop).
5. For Redirect URI, enter myapp://auth.
6. Under Permissions, select the Grant admin consent to openid and offline_access permissions check box.
7. Select Register.
8. Record the Application (client) ID for use in a later step.

Next, specify that the application should be treated as a public client:

1. In the left menu, under Manage, select Authentication.
2. Under Advanced settings, in the Allow public client flows section, set Enable the following mobile and desktop flows to Yes.
3. Select Save.
4. Ensure that "allowPublicClient": true is set in the application manifest:
   1. In the left menu, under Manage, select Manifest to open application manifest.
   2. Find allowPublicClient key and ensure its value is set to true.

Now, grant permissions to the API scope you exposed earlier in the IdentityExperienceFramework registration:

1. In the left menu, under Manage, select API permissions.
2. Under Configured permissions, select Add a permission.
3. Select the APIs my organization uses tab, then select the IdentityExperienceFramework application.
4. Under Permission, select the user_impersonation scope that you defined earlier.
5. Select Add permissions. As directed, wait a few minutes before proceeding to the next step.
6. Select Grant admin consent for <your tenant name)>.
7. Select Yes.
8. Select Refresh, and then verify that "Granted for ..." appears under Status for the scope.

---

Custom policy starter pack

Custom policies are a set of XML files you upload to your Azure AD B2C tenant to define technical profiles and user journeys. We provide starter packs 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. For a more in-depth guide to Azure AD B2C custom policies, follow our custom policies how-to guide series.

• 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.
• SocialAndLocalAccountsWithMFA - Enables social, local, and multifactor authentication options.

Each starter pack contains:

• Base file - Few modifications are required to the base. Example: TrustFrameworkBase.xml
• Localization file - This file is where localization changes are made. Example: TrustFrameworkLocalization.xml
• Extension file - This file is where most configuration changes are made. Example: TrustFrameworkExtensions.xml
• Relying party files - Task-specific files called by your application. Examples: SignUpOrSignin.xml, ProfileEdit.xml, PasswordReset.xml

In this article, you edit the XML custom policy files in the SocialAndLocalAccounts starter pack. If you need an XML editor, try Visual Studio Code, a lightweight cross-platform editor.

Get the starter pack

Get the custom policy starter packs from GitHub, then update the XML files in the SocialAndLocalAccounts starter pack with your Azure AD B2C tenant name.

1. Download the .zip file or clone the repository:

   git clone https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack
   

2. In all of the files in the SocialAndLocalAccounts directory, replace the string yourtenant with the name of your Azure AD B2C tenant.

   For example, if the name of your B2C tenant is contosotenant, all instances of yourtenant.partner.onmschina.cn become contosotenant.partner.onmschina.cn.

Add application IDs to the custom policy

Add the application IDs to the extensions file TrustFrameworkExtensions.xml.

1. Open SocialAndLocalAccounts/TrustFrameworkExtensions.xml and find the element <TechnicalProfile Id="login-NonInteractive">.
2. Replace both instances of IdentityExperienceFrameworkAppId with the application ID of the IdentityExperienceFramework application that you created earlier.
3. Replace both instances of ProxyIdentityExperienceFrameworkAppId with the application ID of the ProxyIdentityExperienceFramework application that you created earlier.
4. Save the file.

Add Facebook as an identity provider

The SocialAndLocalAccounts starter pack includes Facebook social sign in. Facebook isn't required for using custom policies, but we use it here to demonstrate how you can enable federated social login in a custom policy. If you don't need to enable federated social login, use the LocalAccounts starter pack instead, and skip to the Upload the policies section.

Create the Facebook key

Add your Facebook application's App Secret as a policy key. You can use the App Secret of the application you created as part of this article's prerequisites.

1. Sign in to the Azure portal.
2. If you have access to multiple tenants, select the Settings icon in the top menu to switch to your Azure AD B2C tenant from the Directories + subscriptions menu.
3. In the Azure portal, search for and select Azure AD B2C.
4. On the overview page, under Policies, select Identity Experience Framework.
5. Select Policy Keys and then select Add.
6. For Options, choose Manual.
7. For Name, enter FacebookSecret. The prefix B2C_1A_ might be added automatically.
8. In Secret, enter your Facebook application's App Secret from developers.facebook.com. This value is the secret, not the application ID.
9. For Key usage, select Signature.
10. Select Create.

Update TrustFrameworkExtensions.xml in custom policy starter pack

In the SocialAndLocalAccounts/TrustFrameworkExtensions.xml file, replace the value of client_id with the Facebook application ID and save changes.

<TechnicalProfile Id="Facebook-OAUTH">
  <Metadata>
  <!--Replace the value of client_id in this technical profile with the Facebook app ID"-->
    <Item Key="client_id">00000000000000</Item>

Upload the policies

1. Select the Identity Experience Framework menu item in your B2C tenant in the Azure portal.
2. Select Upload custom policy.
3. In this order, upload the policy files:
   1. TrustFrameworkBase.xml
   2. TrustFrameworkLocalization.xml
   3. TrustFrameworkExtensions.xml
   4. SignUpOrSignin.xml
   5. ProfileEdit.xml
   6. PasswordReset.xml

As you upload the files, Azure adds the prefix B2C_1A_ to each.

Test the custom policy

1. Under Custom policies, select B2C_1A_signup_signin.
2. For Select application on the overview page of the custom policy, select the web application you wish to test, such as the one named webapp1.
3. Make sure that the Reply URL is https://jwt.ms.
4. Select Run now.
5. Sign up using an email address.
6. Select Run now again.
7. Sign in with the same account to confirm that you have the correct configuration.
8. Select Run now again, and select Facebook to sign in with Facebook and test the custom policy.