Collect user attributes during sign-up

User attributes are values collected from the user during self-service sign-up. In the user flow settings, you can select from a set of built-in user attributes you want to collect from customers. You can also create custom user attributes and add them to your sign-up user flow. On the sign-up page the user enters the information, and it's stored with their profile in your directory. This demo shows the use of built-in attribute and custom attribute called special diet.

Prerequisites

Before you start make sure you have configured the following:
  1. Create a tenant and add admin accounts
  2. Register a web application
  3. Create a user flow

We started by creating the special diet custom user attribute. To do so, sign in to the Microsoft Entra admin center and browse to External Identities > Overview. Then, select Custom user attributes.

The list contains all user attributes available in the tenant, including any custom user attributes that have been created. The Attribute type column indicates whether an attribute is built-in or custom. Select Add to add a new attribute.

In the Add an attribute pane, enter a Name for the custom attribute for example, SpecialDiet. In Data Type, choose String. In the Description, enter a description of the custom attribute for internal use. This description isn't visible to the user.

After you added the custom user attribute to your tenant, proceed to include the custom user attribute in a sign-up flow. Browse to Identity > External Identities > User flows. Then, select a user flow from the list.

Select User attributes. The list includes any custom user attributes you defined as described in the previous section. For example, the new SpecialDiet now appears in the list. Choose all the attributes you want to collect from the user during sign-up, and select Save.

In the last step you configure the sign-up page layout. In the page layout you can indicate which attributes are required and arrange the display order. You can also edit attribute labels, create radio buttons or checkboxes, and more. For this demo, we add a label to the attribute named SpecialDiet. Under Customize, select Page layouts. The attributes you chose to collect appear. Edit the label for any attribute by selecting the value in the Label column and modifying the text.

Dependencies

  • User flow

1. Create custom attribute

To a create custom attribute, run the following Microsoft Graph.

POST https://graph.microsoft.com/beta/identity/userFlowAttributes
{
    "displayName": "SpecialDiet",
    "description": "Customer's special diet",
    "dataType": "string"
}
        
1.1 Copy the custom attribute
From the response, copy the value of the custom attribute id. For example:
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identity/userFlowAttributes/$entity",
    "id": "extension_12345678900000000000000012345678_SpecialDiet",
    "displayName": "SpecialDiet",
    "description": "Customer's special diet",
    "userFlowAttributeType": "custom",
    "dataType": "string"
}  
        

2. Add attribute to a user flow

To add an attribute to a user flow, run the Microsoft Graph below. Replace the {user-flow-ID} with your user flow ID. Replace the {attribute-ID} with your attribute ID from the previous step.

POST https://graph.microsoft.com/beta/identity/authenticationEventsFlows/{user-flow-ID}/microsoft.graph.externalUsersSelfServiceSignUpEventsFlow/onAttributeCollection/microsoft.graph.onAttributeCollectionExternalUsersSelfServiceSignUp/attributes/$ref
{
    "@odata.id":"https://graph.microsoft.com/beta/identity/userFlowAttributes/{attribute-ID}"
}
        
POST https://graph.microsoft.com/beta/identity/authenticationEventsFlows/12345678-1234-1234-1234-123456789012/microsoft.graph.externalUsersSelfServiceSignUpEventsFlow/onAttributeCollection/microsoft.graph.onAttributeCollectionExternalUsersSelfServiceSignUp/attributes/$ref
{
    "@odata.id":"https://graph.microsoft.com/beta/identity/userFlowAttributes/extension_98765432200c4c148da909f1d84b7b65_SpecialDiet"
}
            

3. [Optional] Update the page layout

Usually the attribute appears at the bottom on the sign-up page. You can update the sign-up page layout. In the page layout you can indicate which attributes are required and arrange the display order. You can also edit attribute labels, create radio buttons or checkboxes, and more.

To do so, you need to update the user flow. In the request body, supply only the values for properties that should be updated. Existing properties that aren't included in the request body maintains their previous values or be recalculated based on changes to other property values.

Replace the {user-flow-ID} with your user flow ID. Replace the {attribute-ID} with your attribute ID.

PATCH https://graph.microsoft.com/beta/identity/authenticationEventsFlows/{user-flow-ID}
{
    "@odata.type": "#microsoft.graph.externalUsersSelfServiceSignUpEventsFlow",
    "onAttributeCollection": {
        "@odata.type": "#microsoft.graph.onAttributeCollectionExternalUsersSelfServiceSignUp",
        "attributeCollectionPage": {
            "customStringsFileId": null,
            "views": [
                {
                    "title": null,
                    "description": null,
                    "inputs": [
                        {
                            "attribute": "email",
                            "label": "Email Address",
                            "inputType": "text",
                            "defaultValue": null,
                            "hidden": true,
                            "editable": false,
                            "writeToDirectory": true,
                            "required": true,
                            "validationRegEx": "^[a-zA-Z0-9.!#$%&’'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*$",
                            "options": []
                        },
                        {
                            "attribute": "displayName",
                            "label": "Display Name",
                            "inputType": "text",
                            "defaultValue": null,
                            "hidden": false,
                            "editable": true,
                            "writeToDirectory": true,
                            "required": true,
                            "validationRegEx": "^.*",
                            "options": []
                        },
                        {
                            "attribute": "country",
                            "label": "Country/Region",
                            "inputType": "radioSingleSelect",
                            "defaultValue": null,
                            "hidden": false,
                            "editable": true,
                            "writeToDirectory": true,
                            "required": false,
                            "validationRegEx": "^.*",
                            "options": [
                                {
                                    "label": "Australia",
                                    "value": "au"
                                },
                                {
                                    "label": "Spain",
                                    "value": "es"
                                },
                                {
                                    "label": "United States",
                                    "value": "us"
                                }
                            ]
                        },
                        {
                            "attribute": "city",
                            "label": "City",
                            "inputType": "text",
                            "defaultValue": null,
                            "hidden": false,
                            "editable": true,
                            "writeToDirectory": true,
                            "required": true,
                            "validationRegEx": "^.*",
                            "options": []
                        },                        {
                            "attribute": "{attribute-ID}",
                            "label": "Special diet",
                            "inputType": "text",
                            "defaultValue": null,
                            "hidden": false,
                            "editable": true,
                            "writeToDirectory": true,
                            "required": false,
                            "validationRegEx": "^.*",
                            "options": []
                        }
                    ]
                }
            ]
        }
    }
}