Edit

Overview of custom security attributes using the Microsoft Graph API

  • Article

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

This article provides an overview of how to use the Microsoft Graph API to programmatically define and assign your own custom security attributes.

Key resource types

The following are the building blocks of custom security attributes.

Attribute sets

An attribute set is a group of related custom security attributes. The following are the general characteristics of attribute sets:

  • Name can't include spaces or special characters.
  • Can't be renamed or deleted.
  • Can be delegated to other users to define and assign custom security attributes.

To configure attribute sets, use the attributeSet resource type.

Custom security attribute definitions

A custom security attribute definition is the schema of a custom security attribute or key-value pair. For example, the custom security attribute name, description, data type, and predefined values. The following are the general characteristics of custom security attributes definitions:

  • Name can't include spaces or special characters.
  • Can't be renamed or deleted, but can be deactivated.
  • Must be part of an attribute set.

To configure custom security attribute definitions, use the customSecurityAttributeDefinition resource type.

Allowed values

Allowed values represent the predefined values of a custom security attribute. The following are the general characteristics of allowed values:

  • Values can include spaces, but some special characters are not allowed.
  • Can't be renamed or deleted, but can be deactivated.
  • More predefined values can be added later.
  • Can be of Boolean, Integer, or String data types.

To configure allowed values, use the allowedValue resource type.

Which directory objects support custom security attributes?

Custom security attributes can be assigned to the following objects by using the customSecurityAttributes property. Directory synced users from an on-premises Active Directory can also be assigned custom security attributes.

For examples of custom security attribute assignments, see Examples: Assign, update, list, or remove custom security attribute assignments using the Microsoft Graph API.

Limits and constraints

For a list of the limits and constraints for custom security attributes, see Limits and constraints.

Permissions

To manage custom security attributes, the calling principal must be assigned one of the following Microsoft Entra roles. 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 appropriate custom security attributes permissions.

Next steps