Create Custom User Attribute in Microsoft Entra ID

5.8K

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.

Microsoft Entra ID allows you to create Custom Security Attributes that you can assign to Microsoft Entra ID users, service principals, and managed identities. The feature is available in all Microsoft Entra ID editions and is included with your Azure subscription.

What is a Custom Security Attribute?

Simply put, it is a key-value pair attribute where you can store information and assign it to Microsoft Entra ID 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 Microsoft Entra ID objects (users, service principals, managed identities.)

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

Who Can Create Custom Security Sets and Definitions?

Before diving in, you should understand the permissions required to create and assign Custom Security Attributes in Microsoft Entra ID. The feature itself is available in all Microsoft Entra ID editions.

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 Microsoft Entra ID.

Creating Custom User Attributes using the Portal

This section covers creating custom attribute sets and defining new custom attributes using the Microsoft Entra ID 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 Microsoft Entra ID 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 Microsoft Entra ID using the portal.

Using Custom Security Attributes for ABAC

While you can use custom security attributes to store additional info about users, their primary use case in modern Microsoft Entra ID environments is Attribute-Based Access Control (ABAC).

ABAC allows access decisions to be based on attribute values instead of static group membership. This method provides more flexible and scalable access management for large organizations.

Here are the common ABAC cases:

• Controlling access to Azure resources using Azure RBAC conditions
• Delegating privileged access based on user classifications
• Restricting application access based on business attributes
• Supporting authorization and access-control cases through ABAC-enabled Microsoft services and apps

For example, you could create a custom security attribute called DepartmentClassification and assign values such as:

• Finance
• HumanResources
• IT
• Contractors

These attributes can then be referenced by supported authorization systems to make dynamic access decisions.

Example of Using Custom Security Attributes in Conditional Access

For example, you may assign the following custom security attribute:

• Attribute Set: AccessControl
• Attribute: Classification
• Value: Privileged

Keep in mind that Custom Security Attributes are primarily designed for Attribute-Based Access Control (ABAC) cases. Depending on the Microsoft service and feature, you can use attribute values directly/indirectly through supported authorization mechanisms. You should always check current service support before designing Conditional Access/authorization policies around custom security attributes.

Here are the typical cases:

• Requiring MFA for privileged users
• Restricting access from unmanaged devices
• Limiting access to sensitive apps
• Applying stricter sign-in controls for contractors

Such method allows you to make access decisions based on business attributes instead of maintaining large numbers of security groups.

Custom security attributes are especially useful in case you need to reduce the number of Azure AD groups and move toward attribute-driven access management.

You can then use these values for different purposes (such as assigning access, categorizing users, or reporting, to name a few).

Note that in modern Microsoft Entra environments, assigning access through Attribute-Based Access Control (ABAC) is one of the most common use cases for custom security attributes.

Custom Security Attributes and Azure RBAC Conditions

Note that custom Security Attributes can also be used together with Azure RBAC Conditions to implement Attribute-Based Access Control (ABAC) for Azure resources.

For example, you can grant a role assignment only in case a user’s custom security attribute matches a specific value:

• Department = Finance
• Classification = Privileged
• Environment = Production

This enables more granular authorization decisions than traditional role assignments based only on group membership.

Using Custom Security Attributes for Identity Governance

Keep in mind that Custom Security Attributes can also support Identity Governance cases in Microsoft Entra ID. You can use attributes to classify users, contractors, vendors, privileged accounts, or app identities.

These classifications can then be referenced during:

• access reviews
• entitlement management
• lifecycle workflows
• delegated administration models

Note that you can simplify governance and reduce administrative overhead by using attributes instead of large numbers of security groups.

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

   Note. Keep in mind that modern Microsoft Graph PowerShell versions use separate Microsoft.Graph and Microsoft.Graph.Beta modules instead of the legacy Select-MgProfile beta command.

2. When prompted for the permission request, click Accept.
   

   

   If the login is successful, you will see the “Welcome To Microsoft Graph!” message.
   

   

3. Some custom security attribute operations may require Microsoft Graph Beta cmdlets depending on the Microsoft Graph API version available in your environment.In case the required commands are not available in the standard Microsoft.Graph module, you need to install and import the Microsoft.Graph.Beta module:

   Install-Module Microsoft.Graph.Beta -Scope CurrentUserImport-Module Microsoft.Graph.Beta

   You can check the loaded module version by running the command:

   Get-Module Microsoft.Graph*

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@contoso.com:

Update-MgUser -UserId dummy@contoso.com -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@contoso.com -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

Custom Security Attributes are no longer used only for storing additional user metadata. In modern Microsoft Entra ID environments, they play an important role in Attribute-Based Access Control (ABAC), authorization, identity governance, and workload classification cases.

By assigning structured attribute values to users, service principals, and managed identities, you can implement more scalable and flexible access-control models than through traditional group-based methods.

Throughout this blog post, we explored the step-by-step process of creating custom user attributes in Microsoft Entra ID. 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.