Create Custom User Attribute in Azure AD

1.6K

There are fixed user attributes by default in Azure Active Directory. These attributes include the User Principal Name, Display Name, Email Address, etc. Suppose you want to add more custom user attributes, such as Hire date, Position, and Business title – those attributes don’t exist.

But if you have at least the Azure AD Premium P1 license in your tenant, Azure AD allows you to create Custom Security Attributes that you can assign to Azure AD users.

Related post. How to Create Custom Attributes in Active Directory?

What is a Custom Security Attribute?

Simply put, it is a key-value pair attribute where you can store information and assign it to Azure AD users, service principals, and managed identities. You can then use these values for different purposes, such as assigning access, categorizing users, or reporting, to name a few.

Custom security attributes are contained within custom security attribute sets. There can be multiple custom security attribute sets and multiple custom security attributes defined in each. But here are the limits that you should know.

• A custom attribute value can be a string, integer, or Boolean.
• You can assign up to 100 pre-defined values to each custom attribute. Pre-defined values are helpful when a fixed set of values is available to assign.
• There can be up to 500 active custom security attributes in your tenant. Deactivated attributes are excluded.
• Custom attribute sets cannot be renamed, deleted, or deactivated. You can only edit the description and the maximum number of attributes it can have.
• Custom attributes cannot be renamed, edited, or deleted. They can only be deactivated.
• Deactivated custom attribute names cannot be reused within the same custom attribute set.
• Deactivated custom attributes are not automatically removed from their assigned Azure AD objects (users, service principals, managed identities.)

Who Can Create Custom Security Sets and Definitions?

Before diving in, you should understand the requirements that would allow you to create custom user attributes in Azure AD.

• Your tenant must have an Azure AD Premium P1 license.
• Your administrator account must have the following roles.
  • Attribute Definition Administrator role to create attribute sets and definitions.
  • Attribute Assignment Administrator role to assign custom user attributes. Global administrators and other administrators do not have this role by default.

Once you fit these requirements, you can create custom user attributes in Azure AD.

Creating Custom User Attributes using the Portal

This section covers creating custom attribute sets and defining new custom attributes using the Azure AD portal.

In this example, we’ll create a custom security attribute set called Job. Refer to the image below.

To begin, open your browser, navigate to Microsoft Entra, and log in with your administrator account.

After logging in, follow the next section to create attribute sets, define attributes, and assign the attributes to Azure AD users.

Create the Custom User Attribute Set

1. On the Microsoft Entra admin center, navigate to Identity → Protection → Custom security attributes.
   
2. Click the “Add attribute set” button. If the button is greyed-out, you do not have the correct permissions. Make sure you have the Attribute Definition Administrator role first.
   
3. Enter the attribute set name, description, and the number of attributes (500 maximum).
   

Create the Custom User Attribute Definitions

1. Click the newly created attribute set.
   
2. Under the “Active attributes” section, click the “Add attribute” button.
   
3. Enter the following details:
   • Attribute name — A maximum of 32 characters with no spaces and special characters.
   • Description — Optional and limited to 128 characters long.
   • Data type — Choose between String, Integer, and Boolean.
   • Allow multiple values to be assigned — Select Yes or No depending on whether to allow multiple values.
   • Only allow predefined values to be assigned — Select Yes or No, depending on whether you want to create a pre-defined list of values.
   • Predefined values — Add pre-defined values if you selected Yes in the above setting.
     
4. Repeat the previous step to add more custom attributes as needed. Ultimately, you will have created all custom attribute definitions, similar to the screenshot below.
   

Assign Custom User Attributes

1. In the Microsoft Entra admin center, navigate to Identity → Users → Active Users, and click the username from the list.
   
2. On the user’s properties page, click the “Custom security attributes (preview)” item under the Manage section and click the “Add assignment” button.
   
3. Select the custom attribute set from the Attribute set dropdown.
   
4. Select the custom user attribute from the “Attribute name” dropdown.
   
5. Enter the custom user attribute value.
   
6. Repeat the same steps to assign more custom user attributes. Once you’ve completed the attribute assignment, click the Save button.
   

That’s it! That’s how you create and assign custom user attributes in Azure AD using the portal.

Creating Custom User Attributes using PowerShell

Another way to work with custom user attributes is through Microsoft Graph PowerShell. This method is beneficial if you’re creating and assigning attributes to multiple users.

In this example, we’ll create a new custom attribute set called Personal based on the below screenshot.

Connect to Microsoft Graph API PowerShell

This process requires you to install the Microsoft Graph PowerShell SDK on your computer.

1. Open PowerShell and connect to Microsoft Graph. The required scopes (permissions) are defined in the $scopes variable.

   # 'CustomSecAttributeDefinition.ReadWrite.All' = full permission to manage custom attributes. 
   
   # 'CustomSecAttributeAssignment.ReadWrite.All' = full access to assign custom user attributes. 
   
   # 'User.ReadWrite.All' = full permission to assign custom user attributes. 
   
   $scopes = @( 
   
   'CustomSecAttributeDefinition.ReadWrite.All', 
   
   'CustomSecAttributeAssignment.ReadWrite.All', 
   
   'User.ReadWrite.All' 
   
   ) 
   
   Connect-MgGraph -Scopes $scopes -TenantId icuc.ml

2. When prompted for the permission request, click Accept.
   
   If the login is successful, you will see the “Welcome To Microsoft Graph!” message.
   
3. The commands we’ll use in the remainder of this section are only available in the beta version of the Microsoft Graph API. So let’s switch the profile to beta.

   Select-MgProfile beta

   

Create the Custom User Attribute Set

Run the following command to create a new custom attribute set called Personal. This attribute set will have a maximum of 50 attribute definitions.

$params = @{ 
id = "Personal" 
description = "Personal user attributes" 
maxAttributesPerSet = 50 
} 
New-MgDirectoryAttributeSet -BodyParameter $params

The result shows that the new attribute set “Personal” has been created.

Create the Custom User Attribute Definitions

You must use the following syntax to add new attribute definitions to an attribute set.

Body Parameter	Description
attributeSet	Name of the attribute set that will contain this attribute.
description	Description of this custom attribute of up to 128 characters.
name	Name of this custom attribute. The name must be unique within the same attribute set. The maximum length is up to 32 characters with no spaces and special characters.
type	Valid data types are Boolean, Integer, and String.
isCollection	Set to TRUE or FALSE to indicate whether this attribute accepts multiple values. This property cannot be set to TRUE if the specified data type is Boolean.
isSearchable	Set to TRUE or FALSE to indicate whether this attribute value will be indexed for search.
status	Specify Available or Deprecated. as the initial status of this attribute.
usePreDefinedValuesOnly	Set to TRUE or FALSE to indicate whether this attribute accepts only pre-defined values (TRUE) or free-form values (FALSE).

Now that you’re familiar with the attribute properties, the syntax to create the attribute definition is as follows.

$params = @{ 
attributeSet = "Name of the attribute set" 
description = "Description of this custom attribute" 
isCollection = "$true or $false" 
isSearchable = "$true or $false" 
name = "Name of this custom attribute" 
status = "Available or Deprecated" 
type = "Boolean, Integer, or String" 
usePreDefinedValuesOnly = "$true or $false" 
} 

New-MgDirectoryCustomSecurityAttributeDefinition -BodyParameter $params

For example, this below command creates the custom user attribute called Gender under the Personal attribute set.

$params = @{ 
attributeSet = "Personal" 
name = "Gender" 
description = "The person's gender." 
type = "String" 
status = "Available" 
isCollection = $false 
isSearchable = $true 
usePreDefinedValuesOnly = $false 
} 

New-MgDirectoryCustomSecurityAttributeDefinition -BodyParameter $params

Use the same technique to add more custom attributes as needed. Once done, run the below command to list all custom user attributes inside the attribute set. This command filters the result to show only the attributes in the Personal attribute set.

Get-MgDirectoryCustomSecurityAttributeDefinition -Filter "AttributeSet eq 'Personal'"

Assign Custom User Attributes

Before assigning custom user attributes, you must first define the attribute values in a hashtable like so:

$customSecurityAttributes = @{ 
"[ATTRIBUTE_SET_NAME]" = @{ 
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue" 
"[ATTRIBUTE_NAME_1]" = "[ATTRIBUTE_VALUE]" 
"[ATTRIBUTE_NAME_2]" = "[ATTRIBUTE_VALUE]" 
"[ATTRIBUTE_NAME_3]" = "[ATTRIBUTE_VALUE]" 
} 
}

For example, the below attribute assignment follows the Personal attribute set and attribute definitions.

$customSecurityAttributes = @{ 
"Personal" = @{ 
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue" 
"Gender" = "Female" 
"MaritalStatus" = "Single" 
"DateOfBirth" = "1980-05-22" 
"CountryOfBirth" = "Australia" 
} 
}

Once you’ve composed the custom user attributes, run the following command to assign them to the user. This command assigns the custom user attributes to dummy@icuc.ml.

Update-MgUser -UserId dummy@icuc.ml -CustomSecurityAttributes $customSecurityAttributes

This command does not return results unless there’s an error.

Finally, let’s view the user’s custom attributes:

# Get the user's upn and custom attributes 
$user = Get-MgUser -UserId dummy@icuc.ml -Property userPrincipalName, customSecurityAttributes 
# List attribute sets 
$user.customSecurityAttributes.AdditionalProperties 
# List the custom user attributes under the Job attribute set 
$user.customSecurityAttributes.AdditionalProperties.Job 
# List the custom user attributes under the Personal attribute set 
$user.customSecurityAttributes.AdditionalProperties.Personal

Conclusion

Creating custom user attributes in Azure AD opens up a world of possibilities for organizations looking to tailor their user management experience to specific business needs. By extending the default user schema with custom attributes, you can capture and store additional information about your users, enabling better organization, segmentation, and personalization of user data.

Throughout this blog post, we explored the step-by-step process of creating custom user attributes in Azure AD. We discussed the importance of planning and defining the attribute requirements, followed by implementing the attribute creation using various methods such as the Azure Portal, PowerShell, and Graph API.

However, it’s important to keep in mind that custom user attributes should be used judiciously and with proper consideration for privacy and data protection regulations. Organizations must adhere to relevant compliance standards and ensure they handle user data responsibly.