What are custom security attributes in Azure AD? (Preview) - Azure Active Directory - Microsoft Entra (2023)

  • Article
  • 8 minutes to read

Important

Custom security attributes are 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. These attributes can be used 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).

Why use custom security attributes?

  • Extend user profiles, such as add Employee Hire Date and Hourly Salary to all my employees.
  • Ensure only administrators can see the Hourly Salary attribute in my employees' profiles.
  • Categorize hundreds or thousands of applications to easily create a filterable inventory for auditing.
  • Grant users access to the Azure Storage blobs belonging to a project.

What can I do with custom security attributes?

  • Define business-specific information (attributes) for your tenant.
  • Add a set of custom security attributes on users, applications, Azure AD resources, or Azure resources.
  • Manage Azure AD objects using custom security attributes with queries and filters.
  • Provide attribute governance so attributes determine who can get access.

Features of custom security attributes

  • Available tenant-wide​
  • Include a description
  • Support different data types: Boolean, integer, string​
  • Support single value or multiple values
  • Support user-defined free-form values​ or predefined values
  • Assign custom security attributes to directory synced users from an on-premises Active Directory

The following example shows how you can specify custom security attribute values that are single, multiple, free-form, or predefined.

What are custom security attributes in Azure AD? (Preview) - Azure Active Directory - Microsoft Entra (1)

Objects that support custom security attributes

Currently, you can add custom security attributes for the following Azure AD objects:

  • Azure AD users
  • Azure AD enterprise applications (service principals)
  • Managed identities for Azure resources

How do custom security attributes compare with directory extensions?

Here are some ways that custom security attributes compare with directory extensions:

  • Directory extensions cannot be used for authorization scenarios and attributes because the access control for the extension attributes is tied to the Azure AD object. Custom security attributes can be used for authorization and attributes needing access control because the custom security attributes can be managed and protected through separate permissions.
  • Directory extensions are tied to an application and share the lifecycle of an application. Custom security attributes are tenant wide and not tied to an application.
  • Directory extensions support assigning a single value to an attribute. Custom security attributes support assigning multiple values to an attribute.

Steps to use custom security attributes

  1. Check permissions

    Check that you are assigned the Attribute Definition Administrator or Attribute Assignment Administrator roles. If not, check with your administrator to assign you the appropriate role at tenant scope or attribute set scope. By default, Global Administrator and other administrator roles do not have permissions to read, define, or assign custom security attributes. If necessary, a Global Administrator can assign these roles to themselves.

    What are custom security attributes in Azure AD? (Preview) - Azure Active Directory - Microsoft Entra (2)

  2. Add attribute sets

    Add attribute sets to group and manage related custom security attributes. Learn more

    What are custom security attributes in Azure AD? (Preview) - Azure Active Directory - Microsoft Entra (3)

  3. Manage attribute sets

    Specify who can read, define, or assign custom security attributes in an attribute set. Learn more

    What are custom security attributes in Azure AD? (Preview) - Azure Active Directory - Microsoft Entra (4)

  4. Define attributes

    Add your custom security attributes to your directory. You can specify the date type (Boolean, integer, or string) and whether values are predefined, free-form, single, or multiple. Learn more

    What are custom security attributes in Azure AD? (Preview) - Azure Active Directory - Microsoft Entra (5)

  5. Assign attributes

    Assign custom security attributes to Azure AD objects for your business scenarios. Learn more

    What are custom security attributes in Azure AD? (Preview) - Azure Active Directory - Microsoft Entra (6)

  6. Use attributes

    Filter users and applications that use custom security attributes. Learn more

    Add conditions that use custom security attributes to Azure role assignments for fine-grained access control. Learn more

Terminology

To better understand custom security attributes, you can refer back to the following list of terms.

TermDefinition
attribute definitionThe schema of a custom security attribute or key-value pair. For example, the custom security attribute name, description, data type, and predefined values.
attribute setA collection of related custom security attributes. Attribute sets can be delegated to other users for defining and assigning custom security attributes.
attribute nameA unique name of a custom security attribute within an attribute set. The combination of attribute set and attribute name forms a unique attribute for your tenant.
attribute assignmentThe assignment of a custom security attribute to an Azure AD object, such as users, enterprise applications (service principals), and managed identities.
predefined valueA value that is allowed for a custom security attribute.

Custom security attribute properties

The following table lists the properties you can specify for attribute sets and custom security attributes. Some properties are immutable and cannot be changed later.

PropertyRequiredCan be changed laterDescription
Attribute set name✔️Name of the attribute set. Must be unique within a tenant. Cannot include spaces or special characters.
Attribute set description✔️Description of the attribute set.
Maximum number of attributes✔️Maximum number of custom security attributes that can be defined in an attribute set. Default value is null. If not specified, the administrator can add up to the maximum of 500 active attributes per tenant.
Attribute set✔️A collection of related custom security attributes. Every custom security attribute must be part of an attribute set.
Attribute name✔️Name of the custom security attribute. Must be unique within an attribute set. Cannot include spaces or special characters.
Attribute description✔️Description of the custom security attribute.
Data type✔️Data type for the custom security attribute values. Supported types are Boolean, Integer, and String.
Allow multiple values to be assigned✔️Indicates whether multiple values can be assigned to the custom security attribute. If data type is set to Boolean, cannot be set to Yes.
Only allow predefined values to be assigned✔️Indicates whether only predefined values can be assigned to the custom security attribute. If set to No, free-form values are allowed. Can later be changed from Yes to No, but cannot be changed from No to Yes. If data type is set to Boolean, cannot be set to Yes.
Predefined valuesPredefined values for the custom security attribute of the selected data type. More predefined values can be added later. Values can include spaces, but some special characters are not allowed.
Predefined value is active✔️Specifies whether the predefined value is active or deactivated. If set to false, the predefined value cannot be assigned to any additional supported directory objects.
Attribute is active✔️Specifies whether the custom security attribute is active or deactivated.

Limits and constraints

Here are some of the limits and constraints for custom security attributes.

ResourceLimitNotes
Attribute definitions per tenant500Applies only to active attributes in the tenant
Attribute sets per tenant500
Attribute set name length32Unicode characters and case insensitive
Attribute set description length128Unicode characters
Attribute name length32Unicode characters and case insensitive
Attribute description length128Unicode characters
Predefined valuesUnicode characters and case sensitive
Predefined values per attribute definition100
Attribute value length64Unicode characters
Attribute values assigned per object50Values can be distributed across single and multi-valued attributes.
Example: 5 attributes with 10 values each or 50 attributes with 1 value each
Special characters not allowed for:
Attribute set name
Attribute name
<space> ` ~ ! @ # $ % ^ & * ( ) _ - + = { [ } ] \| \ : ; " ' < , > . ? /Attribute set name and attribute name cannot start with a number
Special characters allowed for attribute valuesAll special characters
Special characters allowed for attribute values when used with blob index tags<space> + - . : = _ /If you plan to use attribute values with blob index tags, these are the only special characters allowed for blob index tags. For more information, see Setting blob index tags.

Custom security attribute roles

Azure AD provides built-in roles to work with custom security attributes. The Attribute Definition Administrator role is the minimum role you need to manage custom security attributes. The Attribute Assignment Administrator role is the minimum role you need to assign custom security attribute values for Azure AD objects like users and applications. You can assign these roles at tenant scope or at attribute set scope.

RolePermissions
Attribute Definition ReaderRead attribute sets
Read custom security attribute definitions
Attribute Definition AdministratorManage all aspects of attribute sets
Manage all aspects of custom security attribute definitions
Attribute Assignment ReaderRead attribute sets
Read custom security attribute definitions
Read custom security attribute keys and values for users and service principals
Attribute Assignment AdministratorRead attribute sets
Read custom security attribute definitions
Read and update custom security attribute keys and values for users and service principals

Important

By default, Global Administrator and other administrator roles do not have permissions to read, define, or assign custom security attributes.

Microsoft Graph APIs

You can manage custom security attributes programmatically using Microsoft Graph APIs. For more information, see Overview of custom security attributes using the Microsoft Graph API.

You can use an API client such as Graph Explorer or Postman to more easily try the Microsoft Graph APIs for custom security attributes.

What are custom security attributes in Azure AD? (Preview) - Azure Active Directory - Microsoft Entra (7)

Known issues

Here are some of the known issues with custom security attributes:

  • Global Administrators can read audit logs for custom security attribute definitions and assignments.
  • If you have an Azure AD Premium P2 license, you can't add eligible role assignments at attribute set scope.
  • If you have an Azure AD Premium P2 license, the Assigned roles page for a user does not list permanent role assignments at attribute set scope. The role assignments exist, but aren't listed.

Depending on whether you have an Azure AD Premium P1 or P2 license, here are the role assignment tasks that are currently supported for custom security attribute roles:

Role assignment taskPremium P1Premium P2
Permanent role assignments✔️✔️
Eligible role assignmentsn/a✔️
Permanent role assignments at attribute set scope✔️✔️
Eligible role assignments at attribute set scopen/a
Assigned roles page lists permanent role assignments at attribute set scope✔️⚠️
Role assignments exist, but aren't listed

License requirements

Using this feature requires Azure AD Premium P1 licenses. To find the right license for your requirements, see Compare generally available features of Azure AD.

Next steps

  • Add or deactivate custom security attributes in Azure AD
  • Manage access to custom security attributes in Azure AD
  • Assign or remove custom security attributes for a user
Top Articles
Latest Posts
Article information

Author: Nathanael Baumbach

Last Updated: 02/10/2023

Views: 6026

Rating: 4.4 / 5 (75 voted)

Reviews: 82% of readers found this page helpful

Author information

Name: Nathanael Baumbach

Birthday: 1998-12-02

Address: Apt. 829 751 Glover View, West Orlando, IN 22436

Phone: +901025288581

Job: Internal IT Coordinator

Hobby: Gunsmithing, Motor sports, Flying, Skiing, Hooping, Lego building, Ice skating

Introduction: My name is Nathanael Baumbach, I am a fantastic, nice, victorious, brave, healthy, cute, glorious person who loves writing and wants to share my knowledge and understanding with you.