Get started with custom policies in Azure Active Directory B2C

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.

Custom policies are configuration files that define the behavior of your Azure Active Directory B2C (Azure AD B2C) tenant. In this article, you create a custom policy that supports local account sign-up or sign-in by using an email address and password. You also prepare your environment for adding identity providers.

Prerequisites

Add signing and encryption keys

  1. Sign in to the Azure portal
  2. Use the Directory + subscription filter in the top menu to select the directory that contains your Azure AD B2C tenant.
  3. In the left menu, select Azure AD B2C. Or, select All services and search for and select Azure AD B2C.
  4. On the Overview page, 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.

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. Select Policy Keys and then select Add.
  2. For Options, choose Manual.
  3. For Name, enter FacebookSecret. The prefix B2C_1A_ might be added automatically.
  4. In Secret, enter your Facebook application's App Secret from developers.facebook.com. This value is the secret, not the application ID.
  5. For Key usage, select Signature.
  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 your tenant-registered applications, which creates a "local account." Local accounts exist only in your Azure AD B2C tenant.

You 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 current Applications experience, or our new unified App registrations (Preview) experience. Learn more about the new experience.

  1. Select All services in the top-left corner of the Azure portal.
  2. In the search box, enter Azure Active Directory.
  3. Select Azure Active Directory in the search results.
  4. Under Manage in the left-hand menu, select App registrations (Legacy).
  5. Select New application registration.
  6. For Name, enter IdentityExperienceFramework.
  7. For Application type, choose Web app/API.
  8. For Sign-on URL, enter https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com, where your-tenant-name is your Azure AD B2C tenant domain name. All URLs should now be using b2clogin.com.
  9. Select Create. After it's created, copy the application ID and save it to use later.

Register the ProxyIdentityExperienceFramework application

  1. In App registrations (Legacy), select New application registration.
  2. For Name, enter ProxyIdentityExperienceFramework.
  3. For Application type, choose Native.
  4. For Redirect URI, enter https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com, where your-tenant-name is your Azure AD B2C tenant.
  5. Select Create. After it's created, copy the application ID and save it to use later.
  6. Select Settings, then select Required permissions, and then select Add.
  7. Choose Select an API, search for and select IdentityExperienceFramework, and then click Select.
  8. Select the check box next to Access IdentityExperienceFramework, click Select, and then click Done.
  9. Select Grant permissions, and then confirm by selecting Yes.

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:

  • 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 multi-factor authentication options.

Each starter pack contains:

  • Base file - Few modifications are required to the base. Example: TrustFrameworkBase.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.onmicrosoft.com become contosotenant.onmicrosoft.com.

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.

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. TrustFrameworkExtensions.xml
    3. SignUpOrSignin.xml
    4. ProfileEdit.xml
    5. PasswordReset.xml

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

Tip

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

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 named webapp1 that you previously registered.
  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.

Add Facebook as an identity provider

  1. In the SocialAndLocalAccounts/TrustFrameworkExtensions.xml file, replace the value of client_id with the Facebook application ID:

    <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>
    
  2. Upload the TrustFrameworkExtensions.xml file to your tenant.

  3. Under Custom policies, select B2C_1A_signup_signin.

  4. Select Run now and select Facebook to sign in with Facebook and test the custom policy.

Next steps

Next, try adding Azure Active Directory (Azure AD) as an identity provider. The base file used in this getting started guide already contains some of the content that you need for adding other identity providers like Azure AD.

For information about setting up Azure AD as and identity provider, see Set up sign-up and sign-in with an Azure Active Directory account using Active Directory B2C custom policies.