Bulk Assign Custom Security Attributes to Users in Entra ID

Assign a CSA value to users via the Entra admin center

Use this path for small cohorts (<20 users) or as a one-off verification after a scripted run.

Step 1 — Confirm the attribute definition

1. Sign in to the Microsoft Entra admin center at https://entra.microsoft.com as an Attribute Definition Reader (or higher).
2. Navigate to Protection → Custom security attributes.
3. Open the attribute set (e.g. Accounts) and verify the target attribute (e.g. UserType) exists and the desired value (e.g. Employee) is listed as an active allowed value.

Step 2 — Build the user cohort

1. Navigate to Identity → Users → All users.
2. Click Add filter, choose User principal name or Email, and enter the matching fragment (e.g. @contoso.com).
3. Export the filtered list via Download users so you have a record of who was in scope.

Step 3 — Assign the attribute per user

1. Click a user in the filtered list to open their profile.
2. Select the Custom security attributes tab.
3. Click Add assignment.
4. Choose the Attribute set (e.g. Accounts), the Attribute name (e.g. UserType), and the Value (e.g. Employee).
5. Click Save.
6. Repeat for each user in the cohort.

Step 4 — Verify

1. Return to Users → All users and click Columns → add Custom security attributes.
2. Confirm all targeted users now display the expected attribute value.

For more than a handful of users, use the Graph API or PowerShell paths below — the GUI does not offer bulk selection for CSA assignment.

Bulk assignment via Microsoft Graph

The Graph approach is idempotent and auditable. All CSA operations live on the /beta endpoint.

1. List attribute definitions (validate target)

GET https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions

Response (abbreviated):

{
  "value": [
    {
      "id": "Accounts_UserType",
      "attributeSet": "Accounts",
      "name": "UserType",
      "type": "String",
      "status": "Available",
      "usePreDefinedValuesOnly": true
    }
  ]
}

2. List allowed values for the attribute

GET https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions/Accounts_UserType/allowedValues

Confirm the target value (e.g. Employee) is present with isActive: true.

3. Query target users (advanced query)

GET https://graph.microsoft.com/v1.0/users?$filter=endsWith(mail,'@contoso.com')&$select=id,displayName,mail,customSecurityAttributes&$count=true
ConsistencyLevel: eventual

// The ConsistencyLevel: eventual header and $count=true are REQUIRED for endsWith()

4. PATCH each user to assign the attribute

PATCH https://graph.microsoft.com/beta/users/{user-id}
Content-Type: application/json

{
  "customSecurityAttributes": {
    "Accounts": {
      "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
      "UserType": "Employee"
    }
  }
}

Expected response: HTTP 204 No Content.

5. Verify

GET https://graph.microsoft.com/v1.0/users/{user-id}?$select=displayName,customSecurityAttributes

Notes

• Graph does not support $filter on customSecurityAttributes. Pull all candidates and filter client-side.
• PATCH merges at the attribute-set level. Sending UserType: null clears just that attribute; sending Accounts: null clears the entire set.
• Batch up to 20 PATCH calls per $batch request to reduce round-trips.

PowerShell using Microsoft.Graph SDK

The provided PowerShell script automates the full workflow: authenticate, validate the attribute definition, enumerate the target cohort, skip users already tagged, and assign the CSA to the rest with a per-user success/failure report.

Prerequisites

• PowerShell 7+
• Microsoft.Graph module installed (Install-Module Microsoft.Graph -Scope CurrentUser)
• The signed-in admin must hold the Attribute Assignment Administrator directory role

Usage

# Dry run — show what would change without writing
.\Assign-CustomSecurityAttribute.ps1 -MailSuffix '@contoso.com' -AttributeSet 'Accounts' -AttributeName 'UserType' -Value 'Employee' -WhatIf

# Live run
.\Assign-CustomSecurityAttribute.ps1 -MailSuffix '@contoso.com' -AttributeSet 'Accounts' -AttributeName 'UserType' -Value 'Employee'

What the script does

1. Connects to Graph with the minimum scopes required (User.Read.All, CustomSecAttributeDefinition.Read.All, CustomSecAttributeAssignment.ReadWrite.All).
2. Reads the attribute definition and validates usePreDefinedValuesOnly — if true, confirms the supplied -Value is an active allowed value.
3. Queries all users matching endsWith(mail, $MailSuffix) with the correct ConsistencyLevel header.
4. Splits the cohort into already-has and needs-assignment.
5. Sends a PATCH per user, collects outcomes, and writes a CSV report.
6. Honors -WhatIf to preview changes.