Merge pull request #227902 from MicrosoftDocs/main

Publish to live, Sunday 4 PM PST, 2/19

Author: Stacyrch140

articles/active-directory/enterprise-users/media/users-custom-security-attributes/users-attributes-filter.png

@@ -1,10 +1,10 @@
 ---
-title: Assign or remove custom security attributes for a user (Preview) - Azure Active Directory
-description: Assign or remove custom security attributes for a user in Azure Active Directory. 
+title: Assign, update, list, or remove custom security attributes for a user (Preview) - Azure Active Directory
+description: Assign, update, list, or remove custom security attributes for a user in Azure Active Directory. 
 services: active-directory 
 author: rolyon
 ms.author: rolyon
-ms.date: 06/24/2022
+ms.date: 02/20/2023
 ms.topic: how-to
 ms.service: active-directory
 ms.subservice: enterprise-users
@@ -14,13 +14,13 @@ ms.reviewer:
 ms.collection: M365-identity-device-management
 ---
 
-# Assign or remove custom security attributes for a user (Preview)
+# Assign, update, list, or remove custom security attributes for a user (Preview)
 
 > [!IMPORTANT]
 > Custom security attributes are currently in PREVIEW.
 > See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
 
-[Custom security attributes](../fundamentals/custom-security-attributes-overview.md) in Azure Active Directory (Azure AD), part of Microsoft Entra, are business-specific attributes (key-value pairs) that you can define and assign to Azure AD 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, remove, or filter custom security attributes for Azure AD.
+[Custom security attributes](../fundamentals/custom-security-attributes-overview.md) in Azure Active Directory (Azure AD), part of Microsoft Entra, are business-specific attributes (key-value pairs) that you can define and assign to Azure AD 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 Azure AD.
 
 ## Prerequisites
 
@@ -79,20 +79,6 @@ To assign or remove custom security attributes for a user in your Azure AD tenan
 
 1. When finished, select **Save**.
 
-## Remove custom security attribute assignments from a user
-
-1. Sign in to the [Azure portal](https://portal.azure.com) or [Azure AD admin center](https://aad.portal.azure.com).
-
-1. Select **Azure Active Directory** > **Users**.
-
-1. Find and select the user that has the custom security attribute assignments you want to remove.
-
-1. In the Manage section, select **Custom security attributes (preview)**.
-
-1. Add check marks next to all the custom security attribute assignments you want to remove.
-
-1. Select **Remove assignment**.
-
 ## Filter users based on custom security attributes
 
 You can filter the list of custom security attributes assigned to users on the All users page.
@@ -101,9 +87,9 @@ You can filter the list of custom security attributes assigned to users on the A
 
 1. Select **Azure Active Directory** > **Users**.
 
-1. Select **Add filters** to open the Pick a field pane.
+1. Select **Add filter** to open the Add filter pane.
 
-1. For **Filters**, select **Custom security attribute**.
+1. Select **Custom security attributes**.
 
 1. Select your attribute set and attribute name.
 
@@ -115,18 +101,23 @@ You can filter the list of custom security attributes assigned to users on the A
 
 1. To apply the filter, select **Apply**.
 
-## PowerShell
+## Remove custom security attribute assignments from a user
 
-To manage custom security attribute assignments for users in your Azure AD organization, you can use PowerShell. The following commands can be used to manage assignments.
+1. Sign in to the [Azure portal](https://portal.azure.com) or [Azure AD admin center](https://aad.portal.azure.com).
 
-#### Get the custom security attribute assignments for a user
+1. Select **Azure Active Directory** > **Users**.
 
-Use the [Get-AzureADMSUser](/powershell/module/azuread/get-azureadmsuser) command to get the custom security attribute assignments for a user.
+1. Find and select the user that has the custom security attribute assignments you want to remove.
 
-```powershell
-$user1 = Get-AzureADMSUser -Id dbb22700-a7de-4372-ae78-0098ee60e55e -Select CustomSecurityAttributes
-$user1.CustomSecurityAttributes
-```
+1. In the Manage section, select **Custom security attributes (preview)**.
+
+1. Add check marks next to all the custom security attribute assignments you want to remove.
+
+1. Select **Remove assignment**.
+
+## PowerShell
+
+To manage custom security attribute assignments for users in your Azure AD organization, you can use PowerShell. The following commands can be used to manage assignments.
 
 #### Assign a custom security attribute with a multi-string value to a user
 
@@ -168,25 +159,18 @@ $attributesUpdate = @{
 Set-AzureADMSUser -Id dbb22700-a7de-4372-ae78-0098ee60e55e -CustomSecurityAttributes $attributesUpdate 
 ```
 
-## Microsoft Graph API
-
-To manage custom security attribute assignments for users in your Azure AD organization, you can use the Microsoft Graph API. The following API calls can be made to manage assignments. For more information, see [Assign, update, or remove custom security attributes using the Microsoft Graph API](/graph/custom-security-attributes-examples).
-
 #### Get the custom security attribute assignments for a user
 
-Use the [Get a user](/graph/api/user-get?view=graph-rest-beta&preserve-view=true) API to get the custom security attribute assignments for a user.
+Use the [Get-AzureADMSUser](/powershell/module/azuread/get-azureadmsuser) command to get the custom security attribute assignments for a user.
 
-```http
-GET https://graph.microsoft.com/beta/users/{id}?$select=customSecurityAttributes
+```powershell
+$user1 = Get-AzureADMSUser -Id dbb22700-a7de-4372-ae78-0098ee60e55e -Select CustomSecurityAttributes
+$user1.CustomSecurityAttributes
 ```
 
-If there are no custom security attributes assigned to the user or if the calling principal does not have access, the response will look like:
+## Microsoft Graph API
 
-```http
-{
-    "customSecurityAttributes": null
-}
-```
+To manage custom security attribute assignments for users in your Azure AD organization, you can use the Microsoft Graph API. The following API calls can be made to manage assignments. For more information, see [Examples: Assign, update, list, or remove custom security attribute assignments using the Microsoft Graph API](/graph/custom-security-attributes-examples).
 
 #### Assign a custom security attribute with a string value to a user
 
@@ -353,6 +337,61 @@ PATCH https://graph.microsoft.com/beta/users/{id}
 }
 ```
 
+#### Get the custom security attribute assignments for a user
+
+Use the [Get user](/graph/api/user-get?view=graph-rest-beta&preserve-view=true) API to get the custom security attribute assignments for a user.
+
+```http
+GET https://graph.microsoft.com/beta/users/{id}?$select=customSecurityAttributes
+```
+
+If there are no custom security attributes assigned to the user or if the calling principal does not have access, the response will look like:
+
+```http
+{
+    "customSecurityAttributes": null
+}
+```
+
+#### List all users with a custom security attribute assignment that equals a value
+
+Use the [List users](/graph/api/user-list?view=graph-rest-beta&preserve-view=true) API to list all users with a custom security attribute assignment that equals a value. The following example 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'
+
+```http
+GET https://graph.microsoft.com/beta/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry eq 'Canada'
+ConsistencyLevel: eventual
+```
+
+#### List all users with a custom security attribute assignment that starts with a value
+
+Use the [List users](/graph/api/user-list?view=graph-rest-beta&preserve-view=true) API to list all users with a custom security attribute assignment that starts with a value. The following example 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'
+
+```http
+GET https://graph.microsoft.com/beta/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=startsWith(customSecurityAttributes/Marketing/EmployeeId,'GS')
+ConsistencyLevel: eventual
+```
+
+#### List all users with a custom security attribute assignment that does not equal a value
+
+Use the [List users](/graph/api/user-list?view=graph-rest-beta&preserve-view=true) API to list all users with a custom security attribute assignment that does not equal a value. The following example 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'
+
+```http
+GET https://graph.microsoft.com/beta/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry ne 'Canada'
+ConsistencyLevel: eventual
+```
+
 #### Remove a single-valued custom security attribute assignment from a user
 
 Use the [Update user](/graph/api/user-update?view=graph-rest-beta&preserve-view=true) API to remove a single-valued custom security attribute assignment from a user by setting the value to null.
@@ -397,42 +436,6 @@ PATCH https://graph.microsoft.com/beta/users/{id}
 }
 ```
 
-#### Filter all users with an attribute that equals a value
-
-Use the [List users](/graph/api/user-list?view=graph-rest-beta&preserve-view=true) API to filter all users with an attribute that equals a value. The following example, retrieves users with an `AppCountry` attribute that equals `Canada`. You must add `ConsistencyLevel: eventual` in the header. You must also include `$count=true` to ensure the request is routed correctly.
-
-- Attribute set: `Marketing`
-- Attribute: `AppCountry`
-- Filter: AppCountry eq 'Canada'
-
-```http
-GET https://graph.microsoft.com/beta/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry%20eq%20'Canada'
-```
-
-#### Filter all users with an attribute that starts with a value
-
-Use the [List users](/graph/api/user-list?view=graph-rest-beta&preserve-view=true) API to filter all users with an attribute that starts with a value. The following example, retrieves users with an `EmployeeId` attribute that starts with `111`. You must add `ConsistencyLevel: eventual` in the header. You must also include `$count=true` to ensure the request is routed correctly.
-
-- Attribute set: `Marketing`
-- Attribute: `EmployeeId`
-- Filter: EmployeeId startsWith '111'
-
-```http
-GET https://graph.microsoft.com/beta/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=startsWith(customSecurityAttributes/Marketing/EmployeeId,'111')
-```
-
-#### Filter all users with an attribute that does not equal a value
-
-Use the [List users](/graph/api/user-list?view=graph-rest-beta&preserve-view=true) API to filter all users with an attribute that does not equal a value. The following example, retrieves users with a `AppCountry` attribute that does not equal `Canada`. This query will also retrieve users that do not have the `AppCountry` attribute assigned. You must add `ConsistencyLevel: eventual` in the header. You must also include `$count=true` to ensure the request is routed correctly.
-
-- Attribute set: `Marketing`
-- Attribute: `AppCountry`
-- Filter: AppCountry ne 'Canada'
-
-```http
-GET https://graph.microsoft.com/beta/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry%20ne%20'Canada'
-```
-
 ## Frequently asked questions
 
 **Where are custom security attributes for users supported?**
@@ -470,5 +473,5 @@ No, custom security attributes are not supported in B2C tenants and are not rela
 ## Next steps
 
 - [Add or deactivate custom security attributes in Azure AD](../fundamentals/custom-security-attributes-add.md)
-- [Assign or remove custom security attributes for an application](../manage-apps/custom-security-attributes-apps.md)
+- [Assign, update, list, or remove custom security attributes for an application](../manage-apps/custom-security-attributes-apps.md)
 - [Troubleshoot custom security attributes in Azure AD](../fundamentals/custom-security-attributes-troubleshoot.md)

articles/active-directory/enterprise-users/users-custom-security-attributes.md

@@ -590,5 +590,5 @@ No, you can't delete custom security attribute definitions. You can only [deacti
 ## Next steps
 
 - [Manage access to custom security attributes in Azure AD](custom-security-attributes-manage.md)
-- [Assign or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md)
-- [Assign or remove custom security attributes for an application](../manage-apps/custom-security-attributes-apps.md)
+- [Assign, update, list, or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md)
+- [Assign, update, list, or remove custom security attributes for an application](../manage-apps/custom-security-attributes-apps.md)

articles/active-directory/fundamentals/custom-security-attributes-add.md

@@ -198,5 +198,5 @@ The following screenshot shows an example of the audit log. To filter the logs f
 ## Next steps
 
 - [Add or deactivate custom security attributes in Azure AD](custom-security-attributes-add.md)
-- [Assign or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md)
+- [Assign, update, list, or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md)
 - [Troubleshoot custom security attributes in Azure AD](custom-security-attributes-troubleshoot.md)

articles/active-directory/fundamentals/custom-security-attributes-manage.md

@@ -202,4 +202,4 @@ Depending on whether you have an Azure AD Premium P1 or P2 license, here are the
 
 - [Add or deactivate custom security attributes in Azure AD](custom-security-attributes-add.md)
 - [Manage access to custom security attributes in Azure AD](custom-security-attributes-manage.md)
-- [Assign or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md)
+- [Assign, update, list, or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md)

articles/active-directory/fundamentals/custom-security-attributes-overview.md

@@ -8,7 +8,7 @@ ms.service: active-directory
 ms.subservice: fundamentals
 ms.workload: identity
 ms.topic: how-to
-ms.date: 01/14/2022
+ms.date: 02/20/2023
 ms.collection: M365-identity-device-management
 ---
 
@@ -90,7 +90,7 @@ There are no custom security attributes defined and assigned yet for your tenant
 
 **Solution 3**
 
-Add and assign custom security attributes to users or enterprise applications. For more information, see [Add or deactivate custom security attributes in Azure AD](custom-security-attributes-add.md), [Assign or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md), or [Assign or remove custom security attributes for an application](../manage-apps/custom-security-attributes-apps.md).
+Add and assign custom security attributes to users or enterprise applications. For more information, see [Add or deactivate custom security attributes in Azure AD](custom-security-attributes-add.md), [Assign, update, list, or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md), or [Assign, update, list, or remove custom security attributes for an application](../manage-apps/custom-security-attributes-apps.md).
 
 ## Symptom - Custom security attributes cannot be deleted
 
@@ -140,6 +140,26 @@ You are not assigned the required custom security attribute role to make the API
 
 Make sure that you are assigned the required custom security attribute role. For more information, see [Manage access to custom security attributes in Azure AD](custom-security-attributes-manage.md).
 
+## Symptom - Request_UnsupportedQuery error
+
+When you try to call Microsoft Graph APIs for custom security attributes, you see a message similar to the following:
+
+```
+Bad Request - 400
+Request_UnsupportedQuery
+Unsupported or invalid query filter clause specified for property '<AttributeSet>_<Attribute>' of resource 'CustomSecurityAttributeValue'.
+```
+
+**Cause**
+
+The request isn't formatted correctly.
+
+**Solution**
+
+If required, add `ConsistencyLevel=eventual` in the request or the header. You might also need to include `$count=true` to ensure the request is routed correctly. For more information, see [Examples: Assign, update, list, or remove custom security attribute assignments using the Microsoft Graph API](/graph/custom-security-attributes-examples).
+
+![Screenshot of Graph Explorer with ConsistencyLevel header added.](./media/custom-security-attributes-troubleshoot/graph-explorer-consistency-level-header.png)
+
 ## Next steps
 
 - [Manage access to custom security attributes in Azure AD](custom-security-attributes-manage.md)