Azure Active Directory B2C: Built-in policies

The extensible policy framework of Azure Active Directory (Azure AD) B2C is the core strength of the service. Policies fully describe consumer identity experiences such as sign-up, sign-in, or profile editing. For instance, a sign-up policy allows you to control behaviors by configuring the following settings:

  • Account types (social accounts such as Facebook or local accounts such as email addresses) that consumers can use to sign up for the application
  • Attributes (for example, first name, postal code, and shoe size) to be collected from the consumer during sign-up
  • Use of Azure Multi-Factor Authentication
  • The look and feel of all sign-up pages
  • Information (which manifests as claims in a token) that the application receives when the policy run finishes

You can create multiple policies of different types in your tenant and use them in your applications as needed. Policies can be reused across applications. This flexibility enables developers to define and modify consumer identity experiences with minimal or no changes to their code.

Policies are available for use via a simple developer interface. Your application triggers a policy by using a standard HTTP authentication request (passing a policy parameter in the request) and receives a customized token as response. For example, the only difference between requests that invoke a sign-up policy and requests that invoke a sign-in policy is the policy name that's used in the "p" query string parameter:


https://login.microsoftonline.com/contosob2c.onmicrosoft.com/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e      // Your registered Application ID
&redirect_uri=https%3A%2F%2Flocalhost%3A44321%2F    // Your registered Reply URL, url encoded
&response_mode=form_post                            // 'query', 'form_post' or 'fragment'
&response_type=id_token
&scope=openid
&nonce=dummy
&state=12345                                        // Any value provided by your application
&p=b2c_1_siup                                       // Your sign-up policy

https://login.microsoftonline.com/contosob2c.onmicrosoft.com/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e      // Your registered Application ID
&redirect_uri=https%3A%2F%2Flocalhost%3A44321%2F    // Your registered Reply URL, url encoded
&response_mode=form_post                            // 'query', 'form_post' or 'fragment'
&response_type=id_token
&scope=openid
&nonce=dummy
&state=12345                                        // Any value provided by your application
&p=b2c_1_siin                                       // Your sign-in policy

For more information about the policy framework, see this blog post about Azure AD B2C on the Enterprise Mobility and Security Blog.

Create a sign-up or sign-in policy

This policy handles both consumer sign-up & sign-in experiences with a single configuration. Consumers are led down the right path (sign-up or sign-in) depending on the context. It also describes the contents of tokens that the application will receive upon successful sign-ups or sign-ins. A code sample for the sign-up or sign-in policy is available here. It is recommened that you use this policy over a sign-up policy and sign-in policy.

To enable sign-in on your application, you will need to create a sign-in policy. This policy describes the experiences that consumers will go through during sign-in and the contents of tokens that the application will receive on successful sign-ins.

Select Azure AD B2C from the services list in the Azure portal.

Select B2C service

In the policies section of settings, select Sign-up or sign-in policies and click + Add.

Select sign-up or sign-in policies and click Add button

Enter a policy Name for your application to reference. For example, enter SiUpIn.

Select Identity providers and check Email signup. Optionally, you can also select social identity providers, if already configured. Click OK.

Select Email signup as an identity provider and click the OK button

Select Sign-up attributes. Choose attributes you want to collect from the consumer during sign-up. For example, check Country/Region, Display Name, and Postal Code. Click OK.

Select some attributes and click the OK button

Select Application claims. Choose claims you want returned in the authorization tokens sent back to your application after a successful sign-up or sign-in experience. For example, select Display Name, Identity Provider, Postal Code, User is new and User's Object ID.

Select some application claims and click OK button

Click Create to add the policy. The policy is listed as B2C_1_SiUpIn. The B2C_1_ prefix is appended to the name.

Open the policy by selecting B2C_1_SiUpIn. Verify the settings specified in the table then click Run now.

Select policy and run it

Setting Value
Applications Contoso B2C app
Select reply url https://localhost:44316/

A new browser tab opens, and you can verify the sign-up or sign-in consumer experience as configured.

Note

It takes up to a minute for policy creation and updates to take effect.

Create a sign-up policy

To enable sign-up on your application, you need to create a sign-up policy. This policy describes the experiences that consumers go through during sign-up and the contents of tokens that the application receives on successful sign-ups.

Select Azure AD B2C from the services list in the Azure portal.

Select B2C service

Click Sign-up policies.

Click +Add at the top of the blade.

The Name determines the sign-up policy name used by your application. For example, enter SiUp.

Click Identity providers and select Email signup. Optionally, you can also select social identity providers, if already configured. Click OK.

Click Sign-up attributes. Here you choose attributes that you want to collect from the consumer during sign-up. For example, select Country/Region, Display Name, and Postal Code. Click OK.

Click Application claims. Here you choose claims that you want returned in the tokens sent back to your application after a successful sign-up experience. For example, select Display Name, Identity Provider, Postal Code, User is new, and User's Object ID.

Click Create. The policy created appears as B2C_1_SiUp (the B2C_1_ fragment is automatically added) in the Sign-up policies blade.

Open the policy by clicking B2C_1_SiUp.

Select Contoso B2C app in the Applications drop-down and https://localhost:44321/ in the Reply URL / Redirect URI drop-down.

Click Run now. A new browser tab opens, and you can run through the consumer experience of signing up for your application.

Note

It takes up to a minute for policy creation and updates to take effect.

Create a sign-in policy

To enable sign-in on your application, you will need to create a sign-in policy. This policy describes the experiences that consumers will go through during sign-in and the contents of tokens that the application will receive on successful sign-ins.

Select Azure AD B2C from the services list in the Azure portal.

Select B2C service

Click Sign-in policies.

Click +Add at the top of the blade.

The Name determines the sign-in policy name used by your application. For example, enter SiIn.

Click Identity providers and select Local Account SignIn. Optionally, you can also select social identity providers, if already configured. Click OK.

Click Application claims. Here you choose claims that you want returned in the tokens sent back to your application after a successful sign-in experience. For example, select Display Name, Identity Provider, Postal Code and User's Object ID. Click OK.

Click Create. Note that the policy just created appears as B2C_1_SiIn (the B2C_1_ fragment is automatically added) in the Sign-in policies blade.

Open the policy by clicking B2C_1_SiIn.

Select Contoso B2C app in the Applications drop-down and https://localhost:44321/ in the Reply URL / Redirect URI drop-down.

Click Run now. A new browser tab opens, and you can run through the consumer experience of signing into your application.

Note

It takes up to a minute for policy creation and updates to take effect.

Create a profile editing policy

To enable profile editing on your application, you will need to create a profile editing policy. This policy describes the experiences that consumers will go through during profile editing and the contents of tokens that the application will receive on successful completion.

Select Azure AD B2C from the services list in the Azure portal.

Select B2C service

In the policies section of settings, select Profile editing policies and click + Add.

Select Profile editing policies and click the Add button

Enter a policy Name for your application to reference. For example, enter SiPe.

Select Identity providers and check Local Account Signin. Optionally, you can also select social identity providers, if already configured. Click OK.

Select Local Account Signin as an identity provider and click the OK button

Select Profile attributes. Choose attributes the consumer can view and edit in their profile. For example, check Country/Region, Display Name, and Postal Code. Click OK.

Select some attributes and click the OK button

Select Application claims. Choose claims you want returned in the authorization tokens sent back to your application after a successful profile editing experience. For example, select Display Name, Postal Code.

Select some application claims and click OK button

Click Create to add the policy. The policy is listed as B2C_1_SiPe. The B2C_1_ prefix is appended to the name.

Open the policy by selecting B2C_1_SiPe. Verify the settings specified in the table then click Run now.

Select policy and run it

Setting Value
Applications Contoso B2C app
Select reply url https://localhost:44316/

A new browser tab opens, and you can verify the profile editing consumer experience as configured.

Note

It takes up to a minute for policy creation and updates to take effect.

Create a password reset policy

To enable fine-grained password reset on your application, you will need to create a password reset policy. Note that the tenant-wide password reset option specified here. This policy describes the experiences that the consumers will go through during password reset and the contents of tokens that the application will receive on successful completion.

Select Azure AD B2C from the services list in the Azure portal.

Select B2C service

In the policies section of settings, select Password reset policies and click + Add.

Select sign-up or sign-in policies and click the Add button

Enter a policy Name for your application to reference. For example, enter SSPR.

Select Identity providers and check Reset password using email address. Click OK.

Select reset password using email address as an identity provider and click the OK button

Select Application claims. Choose claims you want returned in the authorization tokens sent back to your application after a successful password reset experience. For example, select User's Object ID.

Select some application claims and click OK button

Click Create to add the policy. The policy is listed as B2C_1_SSPR. The B2C_1_ prefix is appended to the name.

Open the policy by selecting B2C_1_SSPR. Verify the settings specified in the table then click Run now.

Select policy and run it

Setting Value
Applications Contoso B2C app
Select reply url https://localhost:44316/

A new browser tab opens, and you can verify the password reset consumer experience in your application.

Note

It takes up to a minute for policy creation and updates to take effect.

Frequently asked questions

When you create a sign-up or sign-in policy (with local accounts), you see a Forgot password? link on the first page of the experience. Clicking this link doesn't automatically trigger a password reset policy.

Instead, the error code AADB2C90118 is returned to your app. Your app needs to handle this error code by invoking a specific password reset policy. For more information, see a sample that demonstrates the approach of linking policies.

Should I use a sign-up or sign-in policy or a sign-up policy and a sign-in policy?

We recommend that you use a sign-up or sign-in policy over a sign-up policy and a sign-in policy.

The sign-up or sign-in policy has more capabilities than the sign-in policy. It also enables you to use page UI customization and has better support for localization.

The sign-in policy is recommended if you don't need to localize your policies, only need minor customization capabilities for branding, and want password reset built into it.

Next steps