Define custom attributes in Azure Active Directory B2C

Before you begin, use the Choose a policy type selector to choose the type of policy you’re setting up. Azure Active Directory B2C offers two methods to define how users interact with your applications: through predefined user flows or through fully configurable custom policies. The steps required in this article are different for each method.

In the Add claims and customize user input using custom policies article you learn how to use built-in user profile attributes. In this article, you enable a custom attribute in your Azure Active Directory B2C (Azure AD B2C) directory. Later, you can use the new attribute as a custom claim in user flows or custom policies simultaneously.

Your Azure AD B2C directory comes with a built-in set of attributes. However, you often need to create your own attributes to manage your specific scenario, for example when:

  • A customer-facing application needs to persist a loyaltyId attribute.
  • An identity provider has a unique user identifier, uniqueUserGUID, that must be persisted.
  • A custom user journey needs to persist the state of the user, migrationStatus, for other logic to operate on.

The terms extension property, custom attribute, and custom claim refer to the same thing in the context of this article. The name varies depending on the context, such as application, object, or policy.

Azure AD B2C allows you to extend the set of attributes stored on each user account. You can also read and write these attributes by using the Microsoft Graph API.

Prerequisites

Create a custom attribute

  1. Sign in to the Azure portal as the global administrator of your Azure AD B2C tenant.
  2. Make sure you're using the directory that contains your Azure AD B2C tenant by switching to it in the top-right corner of the Azure portal. Select your subscription information, and then select Switch Directory.
  3. Choose All services in the top-left corner of the Azure portal, search for and select Azure AD B2C.
  4. Select User attributes, and then select Add.
  5. Provide a Name for the custom attribute (for example, "ShoeSize")
  6. Choose a Data Type. Only String, Boolean, and Int are available.
  7. Optionally, enter a Description for informational purposes.
  8. Select Create.

The custom attribute is now available in the list of User attributes and for use in your user flows. A custom attribute is only created the first time it is used in any user flow, and not when you add it to the list of User attributes.

Use a custom attribute in your user flow

  1. In your Azure AD B2C tenant, select User flows.
  2. Select your policy (for example, "B2C_1_SignupSignin") to open it.
  3. Select User attributes and then select the custom attribute (for example, "ShoeSize"). Select Save.
  4. Select Application claims and then select the custom attribute.
  5. Select Save.

Once you've created a new user using a user flow, which uses the newly created custom attribute, the object can be queried in Microsoft Graph Explorer. Alternatively you can use the Run user flow feature on the user flow to verify the customer experience. You should now see ShoeSize in the list of attributes collected during the sign-up journey, and see it in the token sent back to your application.

Azure AD B2C extensions app

Extension attributes can only be registered on an application object, even though they might contain data for a user. The extension attribute is attached to the application called b2c-extensions-app. Do not modify this application, as it's used by Azure AD B2C for storing user data. You can find this application under Azure AD B2C, app registrations.

Get extensions app's application ID

  1. Sign in to the Azure portal.
  2. Make sure you're using the directory that contains your Azure AD B2C tenant. Select the Directories + subscriptions icon in the portal toolbar.
  3. On the Portal settings | Directories + subscriptions page, find your Azure AD B2C directory in the Directory name list, and then select Switch.
  4. In the left menu, select Azure AD B2C. Or, select All services and search for and select Azure AD B2C.
  5. Select App registrations, and then select All applications.
  6. Select the b2c-extensions-app. Do not modify. Used by AADB2C for storing user data. application.
  7. Copy the Application ID. Example: 11111111-1111-1111-1111-111111111111.

Get extensions app's application properties

  1. Sign in to the Azure portal.
  2. Make sure you're using the directory that contains your Azure AD B2C tenant. Select the Directories + subscriptions icon in the portal toolbar.
  3. On the Portal settings | Directories + subscriptions page, find your Azure AD B2C directory in the Directory name list, and then select Switch.
  4. In the left menu, select Azure AD B2C. Or, select All services and search for and select Azure AD B2C.
  5. Select App registrations, and then select All applications.
  6. Select the b2c-extensions-app. Do not modify. Used by AADB2C for storing user data. application.
  7. Copy the following identifiers to your clipboard and save them:
    • Application ID. Example: 11111111-1111-1111-1111-111111111111.
    • Object ID. Example: 22222222-2222-2222-2222-222222222222.

Modify your custom policy

To enable custom attributes in your policy, provide Application ID and Application Object ID in the AAD-Common technical profile metadata. The AAD-Common technical profile is found in the base Azure Active Directory technical profile, and provides support for Azure AD user management. Other Azure AD technical profiles include the AAD-Common to leverage its configuration. Override the AAD-Common technical profile in the extension file.

  1. Open the extensions file of your policy. For example, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.

  2. Find the ClaimsProviders element. Add a new ClaimsProvider to the ClaimsProviders element.

  3. Insert the Application ID that you previously recorded, between the opening <Item Key="ClientId"> and closing </Item> elements.

  4. Insert the Application ObjectID that you previously recorded, between the opening <Item Key="ApplicationObjectId"> and closing </Item> elements.

    <!-- 
    <ClaimsProviders> -->
      <ClaimsProvider>
        <DisplayName>Azure Active Directory</DisplayName>
        <TechnicalProfiles>
          <TechnicalProfile Id="AAD-Common">
            <Metadata>
              <!--Insert b2c-extensions-app application ID here, for example: 11111111-1111-1111-1111-111111111111-->  
              <Item Key="ClientId"></Item>
              <!--Insert b2c-extensions-app application ObjectId here, for example: 22222222-2222-2222-2222-222222222222-->
              <Item Key="ApplicationObjectId"></Item>
            </Metadata>
          </TechnicalProfile>
        </TechnicalProfiles> 
      </ClaimsProvider>
    <!-- 
    </ClaimsProviders> -->
    

Upload your custom policy

  1. Sign in to the Azure portal.
  2. Make sure you're using the directory that contains your Azure B2C AD tenant. Select the Directories + subscriptions icon in the portal toolbar.
  3. On the Portal settings | Directories + subscriptions page, find your Azure AD B2C directory in the Directory name list, and then select Switch.
  4. Choose All services in the top-left corner of the Azure portal, and then search for and select App registrations.
  5. Select Identity Experience Framework.
  6. Select Upload Custom Policy, and then upload the TrustFrameworkExtensions.xml policy files that you changed.

Note

The first time the Azure AD technical profile persists the claim to the directory, it checks whether the custom attribute exists. If not, it creates the custom attribute.

Create a custom attribute through Azure portal

The same extension attributes are shared between built-in and custom policies. When you add custom attributes via the portal experience, those attributes are registered by using the b2c-extensions-app that exists in every B2C tenant.

You can create these attributes by using the portal UI before or after you use them in your custom policies. When you create an attribute loyaltyId in the portal, you must refer to it as follows:

Name Used in
extension_loyaltyId Custom policy
extension_<b2c-extensions-app-guid>_loyaltyId Microsoft Graph API

The following example demonstrates the use of custom attributes in an Azure AD B2C custom policy claim definition.

<BuildingBlocks>
  <ClaimsSchema>
    <ClaimType Id="extension_loyaltyId">
      <DisplayName>Loyalty Identification</DisplayName>
      <DataType>string</DataType>
      <UserHelpText>Your loyalty number from your membership card</UserHelpText>
      <UserInputType>TextBox</UserInputType>
    </ClaimType>
  </ClaimsSchema>
</BuildingBlocks>

The following example demonstrates the use of a custom attribute in Azure AD B2C custom policy in a technical profile, input, output, and persisted claims.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="extension_loyaltyId"  />
</InputClaims>
<PersistedClaims>
  <PersistedClaim ClaimTypeReferenceId="extension_loyaltyId" />
</PersistedClaims>
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="extension_loyaltyId" />
</OutputClaims>

Using custom attribute with MS Graph API

Microsoft Graph API supports creating and updating a user with extension attributes. Extension attributes in the Graph API are named by using the convention extension_ApplicationClientID_attributename, where the ApplicationClientID is the Application (client) ID of the b2c-extensions-app application. Note that the Application (client) ID as it's represented in the extension attribute name includes no hyphens. For example:

"extension_831374b3bd5041bfaa54263ec9e050fc_loyaltyId": "212342" 

Remove extension attribute

Unlike built-in attributes, extension/custom attributes can be removed. The extension attributes' values can also be removed.

Important

Before you remove the extension/custom attribute, for each account in the directory, set the extension attribute value to null. In this way you explicitly remove the extension attributes’s values. Then continue to remove the extension attribute itself. Extension/custom attribute is queryable using MS Graph API.

Use the following steps to remove extension/custom attribute from a user flow:

  1. Sign in to the Azure portal as the global administrator of your Azure AD B2C tenant.
  2. Make sure you're using the directory that contains your Azure AD B2C tenant:
    1. Select the Directories + subscriptions icon in the portal toolbar.
    2. On the Portal settings | Directories + subscriptions page, find your Azure AD B2C directory in the Directory name list, and then select Switch
  3. Choose All services in the top-left corner of the Azure portal, search for and select Azure AD B2C.
  4. Select User attributes, and then select the attribute you want to delete.
  5. Select Delete, and then select Yes to confirm.

To remove a custom attribute, use MS Graph API, and use the Delete command.

Next steps

Follow the guidance for how to add claims and customize user input using custom policies. This sample uses a built-in claim 'city'. To use a custom attribute, replace 'city' with your own custom attributes.