Manage custom security attribute assignments

Custom security attributes in Microsoft Entra ID are business-specific attributes (key-value pairs) that you can define and assign to Microsoft Entra objects. These attributes can be used to store information, categorize objects, or enforce fine-grained access control over specific Azure resources through Azure attribute-based access control (Azure ABAC).

Custom security attributes are supported for users and service principals only. This article provides examples of how to assign, update, list, or remove different types of custom security attributes for users and applications using Microsoft Graph.

Prerequisites

  • Create custom security attributes. For more information about how to define and manage custom security attribute definitions, see Overview of custom security attributes using Microsoft Graph.
  • For delegated scenarios, the calling must be assigned the following permissions and administrative roles.
    • To assign, update, or remove:
      • Microsoft Entra roles: Attribute Assignment Administrator
      • Microsoft Graph permissions:
        • Users: CustomSecAttributeAssignment.ReadWrite.All and User.Read.All
        • Service principals: CustomSecAttributeAssignment.ReadWrite.All and Application.Read.All
    • To read:

Assign custom security attributes

Example 1: Assign a custom security attribute with a string value to a user

The following example shows how to use the Update user API to assign a custom security attribute with a string value to a user.

  • Attribute set: Engineering
  • Attribute: ProjectDate
  • Attribute data type: String
  • Attribute value: "2022-10-01"

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

Response

HTTP/1.1 204 No Content

Example 2: Assign a custom security attribute with a string value to a service principal

The following example shows how to use the Update servicePrincipal API to assign a custom security attribute with a string value to a service principal.

  • Attribute set: Engineering
  • Attribute: ProjectDate
  • Attribute data type: String
  • Attribute value: "2022-10-01"

Request

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

Response

HTTP/1.1 204 No Content

Example 3: Assign a custom security attribute with a multi-string value to a user

The following example shows how to use the Update user API to assign 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"]

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Project@odata.type":"#Collection(String)",
            "Project":["Baker","Cascade"]
        }
    }
}

Response

HTTP/1.1 204 No Content

Example 4: Assign a custom security attribute with an integer value to a user

The following example shows how to use the Update user API to assign a custom security attribute with an integer value to a user.

  • Attribute set: Engineering
  • Attribute: NumVendors
  • Attribute data type: Integer
  • Attribute value: 4

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "NumVendors@odata.type":"#Int32",
            "NumVendors":4
        }
    }
}

Response

HTTP/1.1 204 No Content

Example 5: Assign a custom security attribute with a multi-integer value to a user

The following example shows how to use the Update user API to assign 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]

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "CostCenter@odata.type":"#Collection(Int32)",
            "CostCenter":[1001,1003]
        }
    }
}

Response

HTTP/1.1 204 No Content

Example 6: Assign a custom security attribute with a Boolean value to a user

The following example shows how to use the Update user API to assign a custom security attribute with a Boolean value to a user.

  • Attribute set: Engineering
  • Attribute: Certification
  • Attribute data type: Boolean
  • Attribute value: true

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Certification":true
        }
    }
}

Response

HTTP/1.1 204 No Content

Update custom security attribute assignments

Example 1: Update a custom security attribute assignment with an integer value for a user

The following example shows how to use the Update user API to update a custom security attribute assignment with an integer value for a user.

  • Attribute set: Engineering
  • Attribute: NumVendors
  • Attribute data type: Integer
  • Attribute value: 8

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "NumVendors@odata.type":"#Int32",
            "NumVendors":8
        }
    }
}

Response

HTTP/1.1 204 No Content

Example 2: Update a custom security attribute assignment with a Boolean value for a user

The following example shows how to use the Update user API to update a custom security attribute assignment with a Boolean value for a user.

  • Attribute set: Engineering
  • Attribute: Certification
  • Attribute data type: Boolean
  • Attribute value: false

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Certification":false
        }
    }
}

Response

HTTP/1.1 204 No Content

List custom security attribute assignments

Example 1: Get the custom security attribute assignments for a user

The following example shows how to use the Get user API to get the custom security attribute assignments for a user.

Attribute #1

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute data type: Collection of Strings
  • Attribute value: ["Baker","Cascade"]

Attribute #2

  • Attribute set: Engineering
  • Attribute: CostCenter
  • Attribute data type: Collection of Integers
  • Attribute value: [1001]

Attribute #3

  • Attribute set: Engineering
  • Attribute: Certification
  • Attribute data type: Boolean
  • Attribute value: true

Attribute #4

  • Attribute set: Marketing
  • Attribute: EmployeeId
  • Attribute data type: String
  • Attribute value: "QN26904"

Request

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

Response

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "EmployeeId": "QN26904"
        },
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        }
    }
}

If there are no custom security attributes assigned to the user or if the calling principal does not have access, the following will be the response:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}

Example 2: List all users with a custom security attribute assignment that equals a value

The following example shows how to use the List users API to list all users with a custom security attribute assignment that equals a value. The 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.

User #1

  • Attribute set: Marketing
  • Attribute: AppCountry
  • Attribute data type: Collection of Strings
  • Attribute value: ["India","Canada"]

User #2

  • Attribute set: Marketing
  • Attribute: AppCountry
  • Attribute data type: Collection of Strings
  • Attribute value: ["Canada","Mexico"]

Request

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry eq 'Canada'
ConsistencyLevel: eventual

Response

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 2,
    "value": [
        {
            "id": "dbaf3778-4f81-4ea0-ac1c-502a293c12ac",
            "displayName": "Jiya",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "Datacenter@odata.type": "#Collection(String)",
                    "Datacenter": [
                        "India"
                    ]
                },
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "India",
                        "Canada"
                    ],
                    "EmployeeId": "KX19476"
                }
            }
        },
        {
            "id": "6bac433c-48c6-4213-a316-1428de32701b",
            "displayName": "Jana",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "Canada",
                        "Mexico"
                    ],
                    "EmployeeId": "GS46982"
                }
            }
        }
    ]
}

Example 3: List all users with a custom security attribute assignment that starts with a value

The following example shows how to use the List users API to list all users with a custom security attribute assignment that starts with a value. The 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.

User #1

  • Attribute set: Marketing
  • Attribute: EmployeeId
  • Attribute data type: String
  • Attribute value: "KX19476"

User #2

  • Attribute set: Marketing
  • Attribute: EmployeeId
  • Attribute data type: String
  • Attribute value: "GS46982"

Request

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=startsWith(customSecurityAttributes/Marketing/EmployeeId,'GS')
ConsistencyLevel: eventual

Response

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 1,
    "value": [
        {
            "id": "6bac433c-48c6-4213-a316-1428de32701b",
            "displayName": "Jana",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "Canada",
                        "Mexico"
                    ],
                    "EmployeeId": "GS46982"
                }
            }
        }
    ]
}

Example 4: List all users with a custom security attribute assignment that does not equal a value

The following example shows how to use the List users API to list all users with a custom security attribute assignment that does not equal a value. The 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.

User #1

  • Attribute set: Marketing
  • Attribute: AppCountry
  • Attribute data type: Collection of Strings
  • Attribute value: ["France"]

All other users

  • AppCountry attribute not added

Request

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry ne 'Canada'
ConsistencyLevel: eventual

Response

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 32,
    "value": [
        {
            "id": "c4f9ecd3-d3c1-4544-b49a-bc9bb62beb67",
            "displayName": "Alain",
            "customSecurityAttributes": null
        },
        {
            "id": "de4f1218-b0fb-4449-b3a0-1e1dd193e6e7",
            "displayName": "Joe",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "Project3@odata.type": "#Collection(String)",
                    "Project3": [
                        "Baker",
                        "Cascade"
                    ],
                    "CostCenter@odata.type": "#Collection(Int32)",
                    "CostCenter": [
                        1001
                    ],
                    "Certification": true
                },
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "EmployeeId": "QN26904"
                }
            }
        },
        {
            "id": "f24d1474-ded5-432d-be08-8abd39921aac",
            "displayName": "Isabella",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "France"
                    ]
                }
            }
        },
        {
            "id": "849e81fe-1109-4d57-9536-a25d537eec1f",
            "displayName": "Dara",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "ProjectDate": "2023-04-12"
                }
            }
        },
        {
            "id": "42c88239-db99-45f0-85af-cbb6c8acb2a3",
            "displayName": "Chandra",
            "customSecurityAttributes": null
        }
    ]
}

Remove custom security attribute assignments

Example 1: Remove a single-valued custom security attribute assignment from a user

The following example shows how to use the Update user API to remove a custom security attribute assignment that supports a single value from a user.

  • Attribute set: Engineering
  • Attribute: ProjectDate
  • Attribute value: null

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":null
        }
    }
}

Response

HTTP/1.1 204 No Content

Example 2: Remove a multi-valued custom security attribute assignment from a user

The following example shows how to use the Update user API to remove a custom security attribute assignment that supports multiple values from a user.

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute value: []

Request

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Project":[]
        }
    }
}

Response

HTTP/1.1 204 No Content

Next step