Assign, update, list, or remove custom security attributes for a user
Custom security attributes in Microsoft Entra ID, part of Microsoft Entra, are business-specific attributes (key-value pairs) that you can define and assign to Microsoft Entra objects. For example, you can assign custom security attribute to filter your employees or to help determine who gets access to resources. This article describes how to assign, update, list, or remove custom security attributes for Microsoft Entra ID.
Prerequisites
To assign or remove custom security attributes for a user in your Microsoft Entra tenant, you need:
- Attribute Assignment Administrator
- Microsoft.Graph module when using Microsoft Graph PowerShell
- AzureADPreview version 2.0.2.138 or later when using Azure AD PowerShell
Important
By default, Global Administrator and other administrator roles do not have permissions to read, define, or assign custom security attributes.
Assign custom security attributes to a user
Tip
Steps in this article might vary slightly based on the portal you start from.
Sign in to the Microsoft Entra admin center as an Attribute Assignment Administrator.
Make sure that you have defined custom security attributes. For more information, see Add or deactivate custom security attribute definitions in Microsoft Entra ID.
Browse to Identity > Users > All users.
Find and select the user you want to assign custom security attributes to.
In the Manage section, select Custom security attributes.
Select Add assignment.
In Attribute set, select an attribute set from the list.
In Attribute name, select a custom security attribute from the list.
Depending on the properties of the selected custom security attribute, you can enter a single value, select a value from a predefined list, or add multiple values.
- For freeform, single-valued custom security attributes, enter a value in the Assigned values box.
- For predefined custom security attribute values, select a value from the Assigned values list.
- For multi-valued custom security attributes, select Add values to open the Attribute values pane and add your values. When finished adding values, select Done.
When finished, select Save to assign the custom security attributes to the user.
Update custom security attribute assignment values for a user
Sign in to the Microsoft Entra admin center as an Attribute Assignment Administrator.
Browse to Identity > Users > All users.
Find and select the user that has a custom security attribute assignment value you want to update.
In the Manage section, select Custom security attributes.
Find the custom security attribute assignment value you want to update.
Once you have assigned a custom security attribute to a user, you can only change the value of the custom security attribute. You can't change other properties of the custom security attribute, such as attribute set or attribute name.
Depending on the properties of the selected custom security attribute, you can update a single value, select a value from a predefined list, or update multiple values.
When finished, select Save.
Filter users based on custom security attribute assignments
You can filter the list of custom security attributes assigned to users on the All users page.
Sign in to the Microsoft Entra admin center as an Attribute Assignment Reader.
Browse to Identity > Users > All users.
Select Add filter to open the Add filter pane.
Select Custom security attributes.
Select your attribute set and attribute name.
For Operator, you can select equals (==), not equals (!=), or starts with.
For Value, enter or select a value.
To apply the filter, select Apply.
Remove custom security attribute assignments from a user
Sign in to the Microsoft Entra admin center as an Attribute Assignment Administrator.
Browse to Identity > Users > All users.
Find and select the user that has the custom security attribute assignments you want to remove.
In the Manage section, select Custom security attributes.
Add check marks next to all the custom security attribute assignments you want to remove.
Select Remove assignment.
PowerShell or Microsoft Graph API
To manage custom security attribute assignments for users in your Microsoft Entra organization, you can use PowerShell or Microsoft Graph API. The following examples can be used to manage assignments.
Assign a custom security attribute with a string value to a user
The following example assigns a custom security attribute with a string value to a user.
- Attribute set:
Engineering - Attribute:
ProjectDate - Attribute data type: String
- Attribute value:
"2024-11-15"
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"ProjectDate" = "2024-11-15"
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Assign a custom security attribute with a multi-string value to a user
The following example assigns a custom security attribute with a multi-string value to a user.
- Attribute set:
Engineering - Attribute:
Project - Attribute data type: Collection of Strings
- Attribute value:
["Baker","Cascade"]
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"Project@odata.type" = "#Collection(String)"
"Project" = @("Baker","Cascade")
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Assign a custom security attribute with an integer value to a user
The following example assigns a custom security attribute with an integer value to a user.
- Attribute set:
Engineering - Attribute:
NumVendors - Attribute data type: Integer
- Attribute value:
4
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"NumVendors@odata.type" = "#Int32"
"NumVendors" = 4
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Assign a custom security attribute with a multi-integer value to a user
The following example assigns a custom security attribute with a multi-integer value to a user.
- Attribute set:
Engineering - Attribute:
CostCenter - Attribute data type: Collection of Integers
- Attribute value:
[1001,1003]
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"CostCenter@odata.type" = "#Collection(Int32)"
"CostCenter" = @(1001,1003)
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Assign a custom security attribute with a Boolean value to a user
The following example assigns a custom security attribute with a Boolean value to a user.
- Attribute set:
Engineering - Attribute:
Certification - Attribute data type: Boolean
- Attribute value:
true
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"Certification" = $true
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Update a custom security attribute assignment with an integer value for a user
The following example updates a custom security attribute assignment with an integer value for a user.
- Attribute set:
Engineering - Attribute:
NumVendors - Attribute data type: Integer
- Attribute value:
8
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"NumVendors@odata.type" = "#Int32"
"NumVendors" = 8
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Update a custom security attribute assignment with a Boolean value for a user
The following example updates a custom security attribute assignment with a Boolean value for a user.
- Attribute set:
Engineering - Attribute:
Certification - Attribute data type: Boolean
- Attribute value:
false
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"Certification" = $false
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Update a custom security attribute assignment with a multi-string value for a user
The following example updates a custom security attribute assignment with a multi-string value for a user.
- Attribute set:
Engineering - Attribute:
Project - Attribute data type: Collection of Strings
- Attribute value:
("Alpine","Baker")
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"Project@odata.type" = "#Collection(String)"
"Project" = @("Alpine","Baker")
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Get the custom security attribute assignments for a user
The following example gets the custom security attribute assignments for a user.
$userAttributes = Get-MgUser -UserId $userId -Property "customSecurityAttributes"
$userAttributes.CustomSecurityAttributes.AdditionalProperties | Format-List
$userAttributes.CustomSecurityAttributes.AdditionalProperties.Engineering
$userAttributes.CustomSecurityAttributes.AdditionalProperties.Marketing
Key : Engineering
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [Project@odata.type, #Collection(String)], [Project, System.Object[]],
[ProjectDate, 2024-11-15]…}
Key : Marketing
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [EmployeeId, GS45897]}
Key Value
--- -----
@odata.type #microsoft.graph.customSecurityAttributeValue
Project@odata.type #Collection(String)
Project {Baker, Alpine}
ProjectDate 2024-11-15
NumVendors 8
CostCenter@odata.type #Collection(Int32)
CostCenter {1001, 1003}
Certification False
Key Value
--- -----
@odata.type #microsoft.graph.customSecurityAttributeValue
EmployeeId KX45897
If there are no custom security attributes assigned to the user or if the calling principal does not have access, the response will be empty.
List all users with a custom security attribute assignment that equals a value
The following example lists all users with a custom security attribute assignment that equals a value. It retrieves users with a custom security attribute named AppCountry with a value that equals Canada. The filter value is case sensitive. You must add ConsistencyLevel=eventual in the request or the header. You must also include $count=true to ensure the request is routed correctly.
- Attribute set:
Marketing - Attribute:
AppCountry - Filter: AppCountry eq 'Canada'
$userAttributes = Get-MgUser -CountVariable CountVar -Property "id,displayName,customSecurityAttributes" -Filter "customSecurityAttributes/Marketing/AppCountry eq 'Canada'" -ConsistencyLevel eventual
$userAttributes | select Id,DisplayName,CustomSecurityAttributes
$userAttributes.CustomSecurityAttributes.AdditionalProperties | Format-List
Id DisplayName CustomSecurityAttributes
-- ----------- ------------------------
4b4e8090-e9ba-4bdc-b2f0-67c3c7c59489 Jiya Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
efdf3082-64ae-495f-b051-855e2d8df969 Jana Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
Key : Engineering
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [Datacenter@odata.type, #Collection(String)], [Datacenter, System.Object[]]}
Key : Marketing
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [AppCountry@odata.type, #Collection(String)], [AppCountry, System.Object[]],
[EmployeeId, KX19476]}
Key : Marketing
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [AppCountry@odata.type, #Collection(String)], [AppCountry, System.Object[]],
[EmployeeId, GS46982]}
List all users with a custom security attribute assignment that starts with a value
The following example lists all users with a custom security attribute assignment that starts with a value. It retrieves users with a custom security attribute named EmployeeId with a value that starts with GS. The filter value is case sensitive. You must add ConsistencyLevel=eventual in the request or the header. You must also include $count=true to ensure the request is routed correctly.
- Attribute set:
Marketing - Attribute:
EmployeeId - Filter: EmployeeId startsWith 'GS'
$userAttributes = Get-MgUser -CountVariable CountVar -Property "id,displayName,customSecurityAttributes" -Filter "startsWith(customSecurityAttributes/Marketing/EmployeeId,'GS')" -ConsistencyLevel eventual
$userAttributes | select Id,DisplayName,CustomSecurityAttributes
$userAttributes.CustomSecurityAttributes.AdditionalProperties | Format-List
Id DisplayName CustomSecurityAttributes
-- ----------- ------------------------
02d52406-be75-411b-b02f-29d7f38dcf62 Chandra Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
efdf3082-64ae-495f-b051-855e2d8df969 Jana Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
d5a1c025-2d79-4ad3-9217-91ac3a4ed8b8 Joe Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
Key : Marketing
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [EmployeeId, GS36348]}
Key : Marketing
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [AppCountry@odata.type, #Collection(String)], [AppCountry, System.Object[]],
[EmployeeId, GS46982]}
Key : Engineering
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [Project@odata.type, #Collection(String)], [Project, System.Object[]],
[ProjectDate, 2024-11-15]…}
Key : Marketing
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [EmployeeId, GS45897]}
List all users with a custom security attribute assignment that does not equal a value
The following example lists all users with a custom security attribute assignment that does not equal a value. It retrieves users with a custom security attribute named AppCountry with a value that does not equal Canada. The filter value is case sensitive. You must add ConsistencyLevel=eventual in the request or the header. You must also include $count=true to ensure the request is routed correctly.
- Attribute set:
Marketing - Attribute:
AppCountry - Filter: AppCountry ne 'Canada'
$userAttributes = Get-MgUser -CountVariable CountVar -Property "id,displayName,customSecurityAttributes" -Filter "customSecurityAttributes/Marketing/AppCountry ne 'Canada'" -ConsistencyLevel eventual
$userAttributes | select Id,DisplayName,CustomSecurityAttributes
Id DisplayName CustomSecurityAttributes
-- ----------- ------------------------
02d52406-be75-411b-b02f-29d7f38dcf62 Chandra Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
eaea4971-7764-4498-9aeb-776496812e75 Isabella Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
d937580c-692c-451f-a507-6758d3bdf353 Alain Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
d5a1c025-2d79-4ad3-9217-91ac3a4ed8b8 Joe Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
23ad8721-f46c-421a-9785-33b0ef474198 Dara Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue
Remove a single-valued custom security attribute assignment from a user
The following example removes a single-valued custom security attribute assignment from a user by setting the value to null.
- Attribute set:
Engineering - Attribute:
ProjectDate - Attribute value:
null
$params = @{
"customSecurityAttributes" = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"ProjectDate" = $null
}
}
}
Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/users/$userId" -Body $params
Remove a multi-valued custom security attribute assignment from a user
The following example removes a multi-valued custom security attribute assignment from a user by setting the value to an empty collection.
- Attribute set:
Engineering - Attribute:
Project - Attribute value:
[]
$customSecurityAttributes = @{
"Engineering" = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
"Project" = @()
}
}
Update-MgUser -UserId $userId -CustomSecurityAttributes $customSecurityAttributes
Frequently asked questions
Where are custom security attribute assignments for users supported?
Custom security attribute assignments for users are supported in Microsoft Entra admin center, PowerShell, and Microsoft Graph APIs. Custom security attribute assignments are not supported in My Apps or Microsoft 365 admin center.
Who can view the custom security attributes assigned to a user?
Only users that have been assigned the Attribute Assignment Administrator or Attribute Assignment Reader roles at tenant scope can view custom security attributes assigned to any users in the tenant. Users cannot view the custom security attributes assigned to their own profile or other users. Guests cannot view the custom security attributes regardless of the guest permissions set on the tenant.
Do I need to create an app to add custom security attribute assignments?
No, custom security attributes can be assigned to user objects without requiring an application.
Why do I keep getting an error trying to save custom security attribute assignments?
You don't have permissions to assign custom security attributes to users. Make sure that you are assigned the Attribute Assignment Administrator role.
Can I assign custom security attributes to guests?
Yes, custom security attributes can be assigned to members or guests in your tenant.
Can I assign custom security attributes to directory synced users?
Yes, directory synced users from an on-premises Active Directory can be assigned custom security attributes.
Are custom security attribute assignments available for dynamic membership rules?
No, custom security attributes assigned to users are not supported for configuring dynamic membership rules.
Are custom security attributes the same as the custom attributes in B2C tenants?
No, custom security attributes are not supported in B2C tenants and are not related to B2C features.
Next steps
- Add or deactivate custom security attribute definitions in Microsoft Entra ID
- Assign, update, list, or remove custom security attributes for an application
- Examples: Assign, update, list, or remove custom security attribute assignments using the Microsoft Graph API
- Troubleshoot custom security attributes in Microsoft Entra ID
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for