Azure Active Directory B2C: Getting started with custom policies

Warning

Custom policies are in public preview.

Note

Custom policies are designed primarily for identity pros who are addressing complex scenarios. Azure Active Directory B2C built-in policies are recommended for most scenarios and provide easier configuration. The two configuration approaches (built-in and custom) can coexist in the same Azure Active Directory B2C tenant. Learn more by reading this overview of custom policies.

After completing the steps in this article, your custom policy will support "local account" sign-up or sign-in using an email and password. You will also prepare your environment for adding additional identity providers (like Facebook or Azure AD). Completion of these steps is encouraged before all other uses of the Azure AD B2C’s Identity Experience Framework and many essential concepts are introduced.

Prerequisites

Before proceeding, ensure that you have an Azure AD B2C tenant. An Azure AD B2C tenant is a container for all your users, apps, policies, and more. If you don't have one already, you need to create one. We strongly encourage all developers to complete the Azure AD B2C built-in policy walkthroughs and configure their application with built-in policies before proceeding. Your applications will work with both types of policies with a trivial change to the policy name to invoke the custom policy.

Access to custom policy editing requires a valid Azure subscription linked to your tenant.

Add signing and encryption keys to your B2C tenant for use by Custom Policies

  1. Navigate to the Identity Experience Framework blade in your Azure AD B2C tenant settings.
  2. Select Policy Keys to view the keys available in your tenant.
  3. Create B2C_1A_TokenSigningKeyContainer if it does not exist:
    • Click on Add
    • Options > Generate
    • Name >TokenSigningKeyContainer The prefix B2C_1A_ may be added automatically.
    • Key type > RSA
    • Dates - use defaults
    • Key usage > Signature
    • Click Create
  4. Create B2C_1A_TokenEncryptionKeyContainer if it does not exist:
    • Click on Add
    • Options > Generate
    • Name >TokenEncryptionKeyContainer The prefix B2C_1A_ may be added automatically.
    • Key type > RSA
    • Dates - use defaults
    • Key usage > Encryption
    • Click Create
  5. Create B2C_1A_FacebookSecret. If you already have a Facebook application secret, add it as a policy key to your tenant. Otherwise, you must create the key with placeholder value so your policies pass validation.
    • Click on Add
    • Options > Manual
    • Name > FacebookSecret The prefix B2C_1A_ may be added automatically.
    • Secret > Enter your FacebookSecret from developers.facebook.com or "0" as a placeholder. This is not your Facebook App ID
    • Key usage > Signature
    • Click Create and confirm creation

Register Identity Experience Framework applications

Azure AD B2C requires you to register two extra applications that are used by the engine to sign-up and sign-in users.

Note

We must create two applications that enable sign-in using local accounts: IdentityExperienceFramework (a web app) and ProxyIdentityExperienceFramework (a native app) with delegated permission from IdentityExperienceFramework app. Local accounts exist only in your tenant. Your end-users sign-up with a unique email:password combination to access your tenant-registered applications.

Create the IdentityExperienceFramework application

  1. In the Azure portal, switch into the context of your Azure AD B2C tenant.
  2. Open the Azure Active Directory blade (not the Azure AD B2C blade). You may need to click > More Services to find it.
  3. Select App registrations.
  4. Click + New application registration.
    • Name: IdentityExperienceFramework
    • Application type: Web app/API
    • Sign-on URL: https://login.microsoftonline.com/yourtenant.onmicrosoft.com where yourtenant is your Azure AD B2C tenant domain name.
  5. Click Create.
  6. Once created, select the newly created application IdentityExperienceFramework, click on Properties, copy the Application ID and save it for later.

Create the proxy Identity Experience Framework application

  1. Select App registrations.
  2. Click + New application registration.
    • Name: ProxyIdentityExperienceFramework
    • Application type: Native
    • Sign-on URL: https://login.microsoftonline.com/yourtenant.onmicrosoft.com where yourtenant is your Azure AD B2C tenant.
  3. Click Create.
  4. Once created, select the application ProxyIdentityExperienceFramework, click on Properties, copy the Application ID and save it for later.
  5. Select Required permissions, then select + Add, and then Select an API.
  6. Search for the name IdentityExperienceFramework, select IdentityExperienceFramework in the results, and then click Select.
  7. Check the checkbox next to Access IdentityExperienceFramework and then click Select.
  8. Click Done.
  9. Click Grant Permissions and confirm Yes

Download starter pack and modify policies

Custom policies are a set of XML files that need to be uploaded to your Azure AD B2C tenant. We provide starter packs to get you going quickly. Each starter pack below has the minimum technical profiles and user journeys needed to achieve the scenarios as described:

  • LocalAccounts - enables the use of local accounts only
  • SocialAccounts - enables the use of social (or federated) accounts only
  • SocialAndLocalAccounts- we will use this one for this walkthrough
  • SocialAndLocalAccountsWithMFA - social, local, and MFA options are included here

Each starterpack contains:

  • The base file of the policy. Few modifications are required to the base.
  • The extension file of the policy. This file is where most configuration changes are made.
  • Relying party files These are task specific files called by your application.
Note

If your XML editor supports validation, you may want to validate the files against the TrustFrameworkPolicy_0.3.0.0.xsd XML schema file that is located in the root folder of the starter pack. XML schema validation identifies errors before uploading.

Let's get started:

  1. Download the "active-directory-b2c-custom-policy-starterpack" from GitHub. Download the zip or run

    git clone https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack
    
  2. Open the SocialAndLocalAccounts folder. The base file (TrustFrameworkBase.xml) in this folder contains content needed for both local and social/corporate accounts. The social content does not interfere with the steps for getting local accounts up and running.
  3. Open TrustFrameworkBase.xml. If you need an XML editor, try Visual Studio Code, a lightweight cross platform editor.
  4. In the root TrustFrameworkPolicy element, update the TenantId and PublicPolicyUri attributes, replacing yourtenant.onmicrosoft.com with your domain name of your Azure AD B2C tenant:

    <TrustFrameworkPolicy
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns="http://schemas.microsoft.com/online/cpim/schemas/2013/06"
    PolicySchemaVersion="0.3.0.0"
    TenantId="yourtenant.onmicrosoft.com"
    PolicyId="B2C_1A_TrustFrameworkBase"
    PublicPolicyUri="http://yourtenant.onmicrosoft.com">
    
    Note

    The PolicyId is the policy name that you will see in the portal and the name by which this policy file will be referenced by other policy files.

  5. Save the file.

  6. Open TrustFrameworkExtensions.xml and make the same two changes by replacing yourtenant.onmicrosoft.com with your Azure AD B2C tenant. Make the same replacement in the element <TenantId> for a total of 3 changes. Save the file.
  7. Open SignUpOrSignIn.xmland make the same changes by replacing yourtenant.onmicrosoft.com with your Azure AD B2C tenant in three places. Save the file.
  8. Open the password reset and profile edit files, and make the same changes by replacing yourtenant.onmicrosoft.com with your Azure AD B2C tenant in three places in each file. Save the files.

Add the application IDs to your custom policy

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

  1. In the extensions file (TrustFrameworkExtensions.xml), find the element <TechnicalProfile Id="login-NonInteractive">.
  2. Replace both instances of IdentityExperienceFrameworkAppId with the application ID of the Identity Experience Framework application that you created earlier. Here is an example:
<Item Key="client_id">8322dedc-cbf4-43bc-8bb6-141d16f0f489</Item>
  1. Replace both instances of ProxyIdentityExperienceFrameworkAppId with the application ID of the Proxy Identity Experience Framework application that you created earlier
  2. Save your extensions file.

Upload the policies to your tenant

  1. In the Azure portal, switch into the context of your Azure AD B2C tenant and open the Azure AD B2C blade.
  2. Click Identity Experience Framework
  3. Select Upload Policy to upload policy files

    Warning

    The custom policy files must be uploaded in the following order:

  4. Upload TrustFrameworkBase.xml.

  5. Upload TrustFrameworkExtensions.xml.
  6. Upload SignUpOrSignin.xml.
  7. Upload your other policy files.

When a file is uploaded, the name of the policy file is prepended with B2C_1A_.

Test the custom policy using "Run Now"

  1. Open the Azure AD B2C Settings and navigate to Identity Experience Framework.
Note

Run now Requires at least one application to be pre-registered on the tenant. Applications must be registered in the B2C tenant, using the Applications menu selection in B2C or in Identity Experience Framework to invoke both built-in and custom policies. Only one registration per application is needed.

Learn how to register applications in the Azure AD B2C Get Started or the Application registration articles.

  1. Open the Relying Party (RP) custom policy that you uploaded B2C_1A_signup_signin, and click the Run now button.

  2. You should be able to sign-up using an email address.

  3. Sign-in with the same account to confirm you have a correct configuration
Note

A common cause of sign-in failure is an improperly configured IdentityExperienceFramework app.

Next steps

Add Facebook as an identity provider

To set up Facebook:

  1. Configure a Facebook application in developers.facebook.com
  2. Add the Facebook application secret to your Azure AD B2C Tenant
  3. Add the Facebook application id in the TrustFrameworkExtensions policy file in the Item Key="client_id":
<TechnicalProfile Id="Facebook-OAUTH">
  <Metadata>
  <!--Replace the value of client_id in this technical profile with your the Facebook App ID"-->
    <Item Key="client_id">00000000000000</Item>
  1. Upload the TrustFrameworkExtensions.xml policy file to your tenant.
  2. Test by using Run now or invoke the policy directly from your registered application.

Add Azure Active Directory as an identity provider

The base file that we used in this getting started guide already contains some of the content that you need for adding other identity providers. To set up login using Azure AD accounts, continue here.

Reference

Overview of Custom Policies in Azure AD B2C using the Identity Experience Framework