Bulk Assign Custom Security Attributes to Users in Entra ID

Custom Security Attributes (CSAs) in Microsoft Entra ID are key-value pairs you define at the tenant level to classify directory objects (users, service principals, devices). They are commonly used to drive Conditional Access scoping, ABAC on Azure resources, license governance, and HR reporting.

A frequent operational task is the bulk assignment of a CSA value to a cohort of users — for example, tagging every employee of a specific domain with Accounts > UserType = Employee so they fall under the correct Conditional Access policy or ABAC role assignment. Doing this one user at a time in the Entra portal is tedious and error-prone; this recipe shows the three reliable paths.

Run this recipe whenever you:

• Onboard a new acquired domain and need to tag its users with a classification value.
• Roll out a new CSA set and need to backfill existing users.
• Periodically reconcile the CSA against a source of truth (HRIS, domain, group membership).

What you will have

• Every user matching the target filter (e.g. mail ending in @contoso.com) carries the specified Custom Security Attribute value.
• A reconciliation report showing users that already had the attribute vs. users who were newly assigned.
• An audit trail of PATCH /beta/users/{id} calls against the directory that can be reviewed in the Entra audit log.
• Confidence that Conditional Access policies, ABAC roles, or reports keyed on that attribute correctly scope the tagged cohort.

Warnings & considerations

• Privileged role required. Assigning CSA values is gated by the Attribute Assignment Administrator role (or equivalent custom role) — Global Admin alone is not sufficient. The operator must be explicitly granted this role before the PATCH calls will succeed.
• Beta endpoint. Custom Security Attribute read/write currently lives on /beta. The payload shape may evolve when it moves to v1.0.
• PATCH is a merge, not a replace. Sending a partial customSecurityAttributes payload merges into the existing attribute set. To remove a value, send null explicitly.
• Predefined values. If the attribute is configured with usePreDefinedValuesOnly = true, you must use an isActive allowed value — free-text will fail.
• Advanced queries. endsWith() requires the ConsistencyLevel: eventual header and $count=true. Without them, the filter returns HTTP 400.
• Do NOT run the bulk assignment without first dry-running the filter and reviewing the user list. A typo in the domain filter can easily tag the wrong cohort.
• Compliance. CSAs may contain data subject to internal governance (e.g. employment classification). Confirm who can read the attribute set before populating it — visibility is governed by attribute-set-level permissions.