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
- An external tenant.
- Permission to manage custom user attributes and the user flow in that tenant.
- An existing sign-up and sign-in user flow to which you can add attributes.
Create custom user attributes
To make a custom attribute available to user flows in your tenant, follow these steps:
Sign in to the Microsoft Entra admin center.
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.
Select Add. In the Add an attribute pane, enter a Name for the custom attribute (for example, "Terms of use").
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 adefaultuserto TextBox. For Microsoft-hosted pages, you can change the input typevalue ofTextBox, but you're abletochange this in a later step (for example if you want to configureradio buttons or multiselectcheckboxes)checkboxes under Page layouts.(Optional) In Description, enter a description of the custom attribute for internal use. This description isn't visible to the user.
Select the user flow from the list.
Select User attributes. The list includes any custom user attributes you
defined as describedcreated in theprevious section. For example, the newtenant, such as Terms of useattribute 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:
Sign in to the Microsoft Entra admin center.
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).
Change the order of display by selecting an attribute and choosing Move up, Move down, Move to top, or Move to bottom.
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).
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:
On the Page layouts page, find the attribute with data type of String that you want to configure as a series of checkboxes.
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.
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:
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.
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.
Select Ok.
Examples:
- To show the attribute on the page but prevent users from editing it, set
hiddentofalseandeditabletofalse. - To hide the attribute from the page while still allowing it to be set programmatically, set
hiddentotrueandeditabletotrue. For example, you can assign a value to the attribute by creating a custom authentication extension for an attribute collection submit event.
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:
- Sign in to the Microsoft Entra admin center.
- Browse to Entra ID > App registrations > All applications.
- Select the application b2c-extensions-app. Do not modify. Used by AADB2C for storing user data.
- On the Overview page, use the Application (client) ID value, for example:
, but remove the hyphens.12345678-abcd-1234-1234-ab12345678900001111-aaaa-2222-bbbb-3333cccc4444
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.
