Microsoft Entra External ID
Fundamentals

User profile attributes

In brief

The article now scopes page-layout and input-control guidance to Microsoft-hosted authentication and directs Native Authentication API integrations to the attribute collection contract. It also updates email attribute API guidance.

What Entra admins need to know

Use the guidance that matches your authentication integration to configure sign-up attributes and API field names correctly.

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.

User profile attributes

[!INCLUDE applies-to-external-only]

The user attributes you collect during sign-up are stored with the user's profile in your directory. You can choose from built-in user attributes or create custom user attributes.

[!INCLUDE authentication-approaches]

Page layout and input-control settings in this article apply to Microsoft-hosted authentication. For the Native Authentication API integrations, use the attribute collection contract.

  • Built-in user attributes, such as city, country/region, and email address, and so on, are available in Microsoft Entra External ID. You can chooseChoose the built-in user attributes you want to collectyour app needs during sign-up.

  • For any additional information you want to collect, you can create custom user attributes. Several custom input controls can be added to the sign-up page to collect the attributes, including text boxes, radio buttons, and check boxes. The following example shows how custom input controls can be used to collect attributes for a loyalty number, terms of use consent forto terms of use, and privacy policy consent.

    :::image type="content" source="media/concept-user-attributes/attribute-collection-page-types-reduced.png" border="false" alt-text="Screenshot of a sign-up page with terms of use and privacy policy checkboxes." lightbox="media/concept-user-attributes/attribute-collection-page-types.png":::

This table summarizes the built-in user attributes you can collect during the sign-up flow:

  • Label in Microsoft Entra admin center is the name of the user attribute as it appears in the Microsoft Entra admin center.
  • Programmable name is the name of the user attribute as used in the user resource of the Microsoft Graph API. You use this name when you want to use this user attribute programmatically, such as in native authenticationFor authentication-specific fields, see the native authentication attribute contract.
  • Data type is the user attribute's data type.
Label in Microsoft Entra admin center Programmable name Data type Remarks
City city String Maximum length is 128 characters.
Country/Region country String Maximum length is 128 characters.
Display Name displayName String Maximum length is 256 characters.
Email Address email String This property can't contain accent characters. InFor API field names, follow the native authentication API, this attribute is referenced asreturned attributeId in the native authentication attribute contract. V1 uses username. for the email identifier.
Given Name givenName String Maximum length is 64 characters.
Job Title jobTitle String Maximum length is 128 characters.
Postal Code postalCode String Maximum length is 40 characters.
State/Province state String Maximum length is 128 characters.
Street Address streetAddress String Maximum length is 1024 characters.
Surname surname String Maximum length is 64 characters.

Custom user attributes

If your app requires more information than the built-in user attributes provide, you can add your own attributes. We refer to these attributes asThese are called custom user attributes.

To define a custom user attribute, you first create the attributeit at the tenant level so it can be used in any user flow in the tenant. Then you assign the attributeit to your sign-up user flow and configureflow. Microsoft-hosted page layout settings control how you want it to appearappears on the sign-up page.Microsoft-hosted pages; your app or self-hosted website controls its own presentation.

Learn how to create custom user attributesFor instructions, see Create custom user attributes article..

Custom user attributes input types

The following input controls describe Microsoft-hosted page layouts. With Embedded native authentication or BYO UX, use the descriptors returned by the Native Authentication API to build your interface.

Before you use custom user attributes, determinechoose the best way to gather user input control for each custom attribute you want to collect. You can collect information from your users during sign-up by using the following input type controls:attribute:

  • String text boxbox.
  • Radio buttonsbuttons.
  • Multiselect checkboxescheckboxes.
  • Numeric text boxbox.
  • Single-select checkboxcheckbox.

Refer to this table to find the appropriate data types and user input types:

Data type User input type Description
String TextBox Free-form text entry field.
String RadioSingleSelect Series of radio buttons with only one selection allowed. The Text for individual radio buttons can include hyperlinks formatted in Markdown language.
String CheckboxMultiSelect Series of one or more checkboxes with multiple selections allowed. The Text for individual checkboxes can include hyperlinks formatted in Markdown language.
Boolean CheckboxSingleSelect Single boolean checkbox with a label. The Label for the checkbox can include hyperlinks formatted in Markdown language.
Int NumericTextBox Free-form integer entry.

Checkboxes and radio buttons can include hyperlinks to other content, such as terms of use and privacy policies. The example at the beginning of this article shows a sign-up page that combines built-in attributes and custom attributes. In the example:

  • The Loyalty Number is a custom attribute with a free-form entry field that accepts a numeric integer. You can configure this format using the Int data type and NumericTextBox user input type.
  • The terms of use and privacy policy custom attributes are separate, single-select checkboxes with labels containing hyperlinks. You can configure a single checkbox using the Boolean data type, which defaults to the CheckboxSingleSelect user input type. Use Markdown language to add hyperlinks to the checkbox label.

Learn how toTo configure their user attributesattribute input types incontrols, see Configure the user input types article..

Where custom user attributes are stored

  • {appId-without-hyphens} is the stripped version of the client ID for the b2c-extensions-app.
  • {custom-attribute-name} is the name you assigned to the custom attribute.

For example, if the client ID of the b2c-extensions-app is 2588a-bcdwh-tfeehj-jeeqw-ertc00001111-aaaa-2222-bbbb-3333cccc4444 and the attribute name is:

  • loyaltyNumber, then the custom attribute is named asextension_2588abcdwhtfeehjjeeqwertc_loyaltyNumberextension_00001111aaaa2222bbbb3333cccc4444_loyaltyNumber.
  • Loyalty Number, then the custom attribute is named asextension_2588abcdwhtfeehjjeeqwertc_LoyaltyNumberextension_00001111aaaa2222bbbb3333cccc4444_LoyaltyNumber. You remove the space and use camel case to separate the words.

Use the Find the application ID for the extensions app article to learn how to find the application ID for the b2c-extensions-app registered in your external tenant.

Attribute collection in your interface

For Embedded native authentication and BYO UX, follow the native authentication attribute contract. Use exact returned attributeId values, current requirements, and validation metadata rather than copying the directory property table into a request. Native Authentication API submissions use string values even when the directory attribute has a Boolean or integer data type.

For an existing V1 SDK integration, use the MSAL Android library for library-specific attribute types. Those types aren't the response schema for the Native Authentication API.

Microsoft Graph APIs

User attributes are referred to as user flow attributes in Microsoft Graph. Use the identityUserFlowAttribute resource type and its associated methods to manage both built-in and custom user flow attributes.

These management APIs have their own permission and resource-token requirements. Signing in through the Native Authentication API doesn't grant directory-management access.

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…