Add or deactivate custom security attributes in Azure AD (Preview)

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. This article describes how to add, edit, or deactivate custom security attributes.

Prerequisites

To add or deactivate custom security attributes, you must have:

Important

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

Add an attribute set

An attribute set is a collection of related attributes. All custom security attributes must be part of an attribute set. Attribute sets cannot be renamed or deleted.

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Click Azure Active Directory > Custom security attributes (Preview).

  3. Click Add attribute set to add a new attribute set.

    If Add attribute set is disabled, make sure you are assigned the Attribute Definition Administrator role. For more information, see Troubleshoot custom security attributes.

  4. Enter a name, description, and maximum number of attributes.

    An attribute set name can be 32 characters with no spaces or special characters. Once you've specified a name, you can't rename it. For more information, see Limits and constraints.

    Screenshot of New attribute set pane in Azure portal.

  5. When finished, click Add.

    The new attribute set appears in the list of attribute sets.

Add a custom security attribute

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Click Azure Active Directory > Custom security attributes (Preview).

  3. On the Custom security attributes page, find an existing attribute set or click Add attribute set to add a new attribute set.

    All custom security attributes must be part of an attribute set.

  4. Click to open the selected attribute set.

  5. Click Add attribute to add a new custom security attribute to the attribute set.

    Screenshot of New attribute pane in Azure portal.

  6. In the Attribute name box, enter a custom security attribute name.

    A custom security attribute name can be 32 characters with no spaces or special characters. Once you've specified a name, you can't rename it. For more information, see Limits and constraints.

  7. In the Description box, enter an optional description.

    A description can be 128 characters long. If necessary, you can later change the description.

  8. From the Data type list, select the data type for the custom security attribute.

    Data type Description
    Boolean A Boolean value that can be true, True, false, or False.
    Integer A 32-bit integer.
    String A string that can be X characters long.
  9. For Allow multiple values to be assigned, select Yes or No.

    Select Yes to allow multiple values to be assigned to this custom security attribute. Select No to only allow a single value to be assigned to this custom security attribute.

  10. For Only allow predefined values to be assigned, select Yes or No.

    Select Yes to require that this custom security attribute be assigned values from a predefined values list. Select No to allow this custom security attribute to be assigned user-defined values or potentially predefined values.

    You can only add the predefined values after you add the custom security attribute by using the Edit attribute page. For more information, see Edit a custom security attribute.

  11. When finished, click Add.

    The new custom security attribute appears in the list of custom security attributes.

  12. If you want to include predefined values, follow the steps in the next section.

Edit a custom security attribute

Once you add a new custom security attribute, you can later edit some of the properties. Some properties are immutable and cannot be changed.

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Click Azure Active Directory > Custom security attributes (Preview).

  3. Click the attribute set that includes the custom security attribute you want to edit.

  4. In the list of custom security attributes, click the ellipsis for the custom security attribute you want to edit and then click Edit attribute.

  5. Edit the properties that are enabled.

  6. If Only allow predefined values to be assigned is Yes, click Add value to add predefined values. Click an existing predefined value to change the Is active? setting.

    An active value is available for assignment to objects. A value that is not active is defined, but not yet available for assignment.

    Screenshot of Add predefined value pane in Azure portal.

Deactivate a custom security attribute

Once you add a custom security attribute, you can't delete it. However, you can deactivate a custom security attribute.

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Click Azure Active Directory > Custom security attributes (Preview).

  3. Click the attribute set that includes the custom security attribute you want to deactivate.

  4. In the list of custom security attributes, add a check mark next to the custom security attribute you want to deactivate.

  5. Click Deactivate attribute.

  6. In the Deactivate attribute dialog that appears, click Yes.

    The custom security attribute is deactivated and moved to the Deactivated attributes list.

PowerShell

To manage custom security attributes in your Azure AD organization, you can also use the PowerShell. The following command can manage attribute sets and custom security attributes.

Get all attribute sets

Get-AzureADMSAttributeSet

Get an attribute set

  • Attribute set: Engineering
Get-AzureADMSAttributeSet -Id "Engineering"

Add an attribute set

  • Attribute set: Engineering
New-AzureADMSAttributeSet -Id "Engineering" -Description "Attributes for engineering team" -MaxAttributesPerSet 10 

Update an attribute set

  • Attribute set: Engineering
Set-AzureADMSAttributeSet -Id "Engineering" -Description "Attributes for cloud engineering team"
Set-AzureADMSAttributeSet -Id "Engineering" -MaxAttributesPerSet 20

Get all custom security attributes

Get-AzureADMSCustomSecurityAttributeDefinition

Get a custom security attribute

  • Attribute set: Engineering
  • Attribute: ProjectDate
Get-AzureADMSCustomSecurityAttributeDefinition -Id "Engineering_ProjectDate"

Add a custom security attribute

  • Attribute set: Engineering
  • Attribute: ProjectDate
  • Attribute data type: String
New-AzureADMSCustomSecurityAttributeDefinition -AttributeSet "Engineering" -Name "ProjectDate" -Description "Target completion date" -Type "String" -Status "Available" -IsCollection $false -IsSearchable $true -UsePreDefinedValuesOnly $true

Update a custom security attribute

  • Attribute set: Engineering
  • Attribute: ProjectDate
Set-AzureADMSCustomSecurityAttributeDefinition -Id "Engineering_ProjectDate" -Description "Target completion date (YYYY/MM/DD)"

Deactivate a custom security attribute

  • Attribute set: Engineering
  • Attribute: Project
Set-AzureADMSCustomSecurityAttributeDefinition -Id "Engineering_Project" -Status "Deprecated"

Get all predefined values

  • Attribute set: Engineering
  • Attribute: Project
Get-AzureADMSCustomSecurityAttributeDefinitionAllowedValue -CustomSecurityAttributeDefinitionId "Engineering_Project"

Get a predefined value

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine
Get-AzureADMSCustomSecurityAttributeDefinitionAllowedValue -CustomSecurityAttributeDefinitionId "Engineering_Project" -Id "Alpine" 

Add a predefined value

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine
Add-AzureADMScustomSecurityAttributeDefinitionAllowedValues -CustomSecurityAttributeDefinitionId "Engineering_Project" -Id "Alpine" -IsActive $true

Deactivate a predefined value

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine
Set-AzureADMSCustomSecurityAttributeDefinitionAllowedValue -CustomSecurityAttributeDefinitionId "Engineering_Project" -Id "Alpine" -IsActive $false

Microsoft Graph API

To manage custom security attributes in your Azure AD organization, you can also use the Microsoft Graph API. The following API calls can be made to manage attribute sets and custom security attributes.

Get all attribute sets

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

Get top attribute sets

GET https://graph.microsoft.com/beta/directory/attributeSets?$top=10

Get attribute sets in order

GET https://graph.microsoft.com/beta/directory/attributeSets?$orderBy=id

Get an attribute set

  • Attribute set: Engineering
GET https://graph.microsoft.com/beta/directory/attributeSets/Engineering

Add an attribute set

  • Attribute set: Engineering
POST https://graph.microsoft.com/beta/directory/attributeSets 
{
    "id":"Engineering",
    "description":"Attributes for engineering team",
    "maxAttributesPerSet":25
}

Update an attribute set

  • Attribute set: Engineering
PATCH https://graph.microsoft.com/beta/directory/attributeSets/Engineering
{
    "description":"Attributes for engineering team",
    "maxAttributesPerSet":20
}

Get all custom security attributes

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

Filter custom security attributes

  • Filter: Attribute name eq 'Project' and status eq 'Available'
GET https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions?$filter=name+eq+'Project'%20and%20status+eq+'Available'
  • Filter: Attribute set eq 'Engineering' and status eq 'Available' and data type eq 'String'
GET https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions?$filter=attributeSet+eq+'Engineering'%20and%20status+eq+'Available'%20and%20type+eq+'String'

Get a custom security attribute

  • Attribute set: Engineering
  • Attribute: ProjectDate
GET https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions/Engineering_ProjectDate

Add a custom security attribute

  • Attribute set: Engineering
  • Attribute: ProjectDate
  • Attribute data type: String
POST https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions
{
    "attributeSet":"Engineering",
    "description":"Target completion date",
    "isCollection":false,
    "isSearchable":true,
    "name":"ProjectDate",
    "status":"Available",
    "type":"String",
    "usePreDefinedValuesOnly": false
}

Add a custom security attribute that supports multiple predefined values

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute data type: Collection of Strings
POST https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions
{
    "attributeSet":"Engineering",
    "description":"Active projects for user",
    "isCollection":true,
    "isSearchable":true,
    "name":"Project",
    "status":"Available",
    "type":"String",
    "usePreDefinedValuesOnly": true
}

Update a custom security attribute

  • Attribute set: Engineering
  • Attribute: ProjectDate
PATCH https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions/Engineering_ProjectDate
{
  "description": "Target completion date (YYYY/MM/DD)",
}

Deactivate a custom security attribute

  • Attribute set: Engineering
  • Attribute: Project
PATCH https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions/Engineering_Project
{
  "status": "Deprecated"
}

Get the properties of a predefined value

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine
GET https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions/Engineering_Project/allowedValues/Alpine

Get all predefined values

  • Attribute set: Engineering
  • Attribute: Project
GET https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions/Engineering_Project/allowedValues

Add a predefined value

You can add predefined values for custom security attributes that have usePreDefinedValuesOnly set to true.

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine
POST https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions/Engineering_Project/allowedValues
{
    "id":"Alpine",
    "isActive":"true"
}

Deactivate a predefined value

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine
PATCH https://graph.microsoft.com/beta/directory/customSecurityAttributeDefinitions/Engineering_Project/allowedValues/Alpine
{
    "isActive":"false"
}

Frequently asked questions

Can you delete custom security attribute definitions?

No, you can't delete custom security attribute definitions. You can only deactivate custom security attribute definitions. Once you deactivate a custom security attribute, it can no longer be applied to the Azure AD objects. Custom security attribute assignments for the deactivated custom security attribute definition are not automatically removed. There is no limit to the number of deactivated custom security attributes. You can have 500 active custom security attribute definitions per tenant with 100 allowed predefined values per custom security attribute definition.

Can you add predefined values when you add a new custom security attribute?

Currently, you can only add predefined values after you defined the custom security attribute by using the Edit attribute page.

Next steps