Microsoft Entra External ID
General

Define Custom User Attributes

In brief

The article now clarifies prerequisites, distinguishes Microsoft-hosted page configuration from native authentication integrations, and adds links to attribute contracts and platform guidance.

What Entra admins need to know

Administrators can use the updated prerequisites and guidance to configure custom attributes and understand which settings apply to hosted sign-up pages.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

Collect custom user attributes during external tenantMicrosoft Entra External ID sign-up

Define custom user attributes in your external tenant, then add them to a sign-up user flow to collect the information your app needs.

[!INCLUDE applies-to-external-onlyauthentication-approaches]

[!NOTE] This article covers attribute collection for browser-delegated authentication using user flows. If you use native authentication, you collect attributes throughFor the MSAL SDK withNative Authentication API integrations, follow the native authentication user attribute builderattribute collection contract. For help choosingSDK setup, see the platform-specific integration guidance.

For an approach,existing V1 SDK integration, see Choose an authentication approach.the MSAL Android library for library-specific attribute types. Those types don't replace the response-driven attribute contract.

If your app requires more information than the built-in user attributes provide, you can add your own attributes. These attributes are called custom user attributes.

To defineCreate a custom user attribute, you first create the attribute at the tenant level so it can be used in's available to any user flow in the tenant. Then you assign the attributeadd it to your sign-up user flow andflow. For Microsoft-hosted pages, you can also configure how you want it to appearappears on the sign-up page.

Learn more about custom user attributes in the User profile attributes article.

Prerequisites

Create custom user attributes

To make a custom attribute available to user flows in your tenant, follow these steps:

  1. Sign in to the Microsoft Entra admin center.

  2. If you have access to multiple tenants, use the Settings icon :::image type="icon" source="media/common/admin-center-settings-icon.png" border="false"::: in the top menu to switch to your external tenant from the Directories + subscriptions menu.

  3. Select Add. In the Add an attribute pane, enter a Name for the custom attribute (for example, "Terms of use").

  4. In Data Type, choose String, Boolean, or Int depending on the type of data and user input control you want to create. String attributes have a default userto TextBox. For Microsoft-hosted pages, you can change the input type value of TextBox, but you're able to change this in a later step (for example if you want to configure radio buttons or multiselect checkboxes)checkboxes under Page layouts.

  5. (Optional) In Description, enter a description of the custom attribute for internal use. This description isn't visible to the user.

  6. Select the user flow from the list.

  7. Select User attributes. The list includes any custom user attributes you defined as describedcreated in the previous section. For example, the newtenant, such as Terms of use attribute now appears in the list.. Choose all the attributes you want to collect from the user during sign-up.

    :::image type="content" source="media/how-to-define-custom-attributes/user-attributes.png" alt-text="Screenshot of the user attribute options on the Create a user flow page." lightbox="media/how-to-define-custom-attributes/user-attributes.png":::

Configure the user input types and page layout

These page layout settings control Microsoft-hosted attribute collection pages.

On the Page layout page, you can indicate which attributes are required and arrange the display order. You can also edit attribute labels, create radio buttons or checkboxes, and add hyperlinks to more content (suchsuch as terms of use or a privacy policy).policy. To configure the hosted page, follow these steps:

  1. Sign in to the Microsoft Entra admin center.

  2. Configure checkboxes or radio buttons:

    • Single-select checkbox: A Boolean attribute type renders as a single-select checkbox on the sign-up page. To configure the text that displays next to the checkbox, select and edit the value in the Label column. Use Markdown language to add hyperlinks. For details, see To configure a single-select checkbox (CheckboxSingleSelect).
    • Multiselect checkboxes: Find the String data type attribute you want to configure, and select the value in the User Input Type column to open the editor pane. Choose the CheckboxMultiSelect user input type and enter the values. For details, see To configure multiselect checkboxes (CheckboxMultiSelect).
    • Radio buttons: Find the String data type attribute you want to configure, and select the value in the User Input Type column to open the editor pane. Choose the RadioSingleSelect user input type and enter the values. For details, see To configure radio buttons (RadioSingleSelect).
  3. Change the order of display by selecting an attribute and choosing Move up, Move down, Move to top, or Move to bottom.

  4. Select the value in the Label column and enter the text you want to display next to the checkbox. Use Markdown language to add hyperlinks. For example:

    • To configure the label for a Terms of use attribute, you could enter:

      I have read and agree to the [terms of use](https://woodgrove.com/terms-of-use).

    • Or, you could combine your terms of use and privacy policy into a single required checkbox:

      I have read and agree to the [terms of use](https://woodgrove.com/terms-of-use) and the [privacy policy](https://woodgrove.com/privacy).

  5. Select Ok.

Configure multiselect checkboxes (CheckboxMultiSelect)

AnA String attribute with a String datacan use the CheckboxMultiSelect input type can be configured as a CheckboxMultiSelect user input type, which is a series ofto display one or more checkboxes that appear under the attribute label. The userDefine text and optional hyperlinks for each checkbox. Users can select one or more checkboxes. You can definemultiple checkboxes; marking the text for individual checkboxes and include hyperlinks to other content. Making this attribute "Required" means that the userthey must select at least one of the checkboxes.one.

To configure multiselect checkboxes, follow these steps:

  1. On the Page layouts page, find the attribute with data type of String that you want to configure as a series of checkboxes.

  2. For each checkbox you want to add, start on a new line and enter the following information:

    • Under Text, enter the text you want to display next to the checkbox. Use Markdown language to add hyperlinks.

    • Under Values, enter a value to be written on the user object and returned as the claim if the user selects the checkbox.

  3. Select Ok.

Configure radio buttons (RadioSingleSelect)

AnA String attribute with a String datacan use the RadioSingleSelect input type can be configured as a RadioSingleSelect user input type, which is a series ofto display radio buttons that appear under the attribute label. The userUsers can select only one radio button.option. You can define the text and optional hyperlinks for individualeach radio buttons and include hyperlinks to other content.button.

To configure radio buttons, follow these steps:

  1. On the Page layouts page, find the attribute with data type of String that you want to configure as a radio button or series of radio buttons.

  2. For each radio button you want to add, start on a new line and enter the following information:

    • Under Text, enter the text you want to display next to the radio button. Use Markdown language to add hyperlinks.

    • Under Values, enter a value to be written on the user object and returned as the claim if the user selects the radio button.

  3. Select Ok.

Examples:

To set the hidden and editable flags using Microsoft Graph, use the authenticationAttributeCollectionInputConfiguration resource type. For reference, see the example on updating the page layout of a self-service sign up user flow.

The Native Authentication API has its own attribute descriptors and submission fields. Use its attribute collection contract, not the Graph configuration property names, when collecting values in your interface.

Find the application ID for the extensions app

Custom user attributes are stored in an app named b2c-extensions-app. After a user enters a value for the custom attribute during sign-up, it's added to the user object and can be called via the Microsoft Graph API using the naming convention extension_{appId-without-hyphens}_{custom-attribute-name} where:

  1. Sign in to the Microsoft Entra admin center.
  2. Browse to Entra ID > App registrations > All applications.
  3. Select the application b2c-extensions-app. Do not modify. Used by AADB2C for storing user data.
  4. On the Overview page, use the Application (client) ID value, for example: 12345678-abcd-1234-1234-ab12345678900001111-aaaa-2222-bbbb-3333cccc4444, but remove the hyphens.

For example, if you create a custom attribute named loyaltyNumber, refer to it as extension_12345678abcd12341234ab123456789_loyaltyNumberextension_00001111aaaa2222bbbb3333cccc4444_loyaltyNumber.

Add custom user attributes to the ID token

When users sign-sign in to your app, the appit receives an ID token, which includes thetoken containing user details. These details are called token claims. If needed, youYou can include a custom user attribute to be availableattributes as a claim in the ID token that's returned to your app. To do so, follow the steps in Add attributes to the ID token returned to your application article.

Next steps

claims. For instructions, see Add attributes to the ID token returned to your application.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…