Assign, update, list, or remove custom security attributes using the Microsoft Graph API (preview)

Important

The custom security attributes feature is currently in preview. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Custom security attributes in Azure Active Directory (Azure AD) are business-specific attributes (key-value pairs) that you can define and assign to Azure AD objects.

This article provides examples of how to assign, update, or remove different types of custom security attributes for users and applications (service principals). Custom security attributes can be assigned or updated only through a PATCH operation in an Update user or Update servicePrincipal request.

Permissions

To manage custom security attributes, the calling principal must be assigned the following Azure AD role. By default, Global Administrator and other administrator roles do not have permissions to read, define, or assign custom security attributes.

Also, the calling principal must be granted the following permissions.

Permissions to read, assign, update, or remove attributes for an application is granted by CustomSecAttributeAssignment.ReadWrite.All. Permissions to read the resource object, such as users, is granted separately using resource object permissions, such as User.Read.All.

Assign custom security attributes

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

The following example shows how 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/beta/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 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/beta/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 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/beta/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 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/beta/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 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/beta/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 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/beta/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 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/beta/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 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/beta/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 attributes assigned to a user

The following example shows how to list a custom security attribute assignment assigned to the user. The custom security attribute is a multi-string value with the following settings:

  • Attribute set: Engineering
  • Attribute: datacenter
  • Attribute data type: Collection of Strings
  • Attribute value: ["Redmond"]

Request

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

Response

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "datacenter@odata.type": "#Collection(String)",
            "datacenter": [
                "Redmond"
            ]
        }
    }
}

Remove custom security attribute assignments

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

The following example shows how 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/beta/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 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/beta/users/{id}
Content-type: application/json

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

Response

HTTP/1.1 204 No Content

Next steps