Add or deactivate custom security attribute definitions in Microsoft Entra ID

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

Prerequisites

To add or deactivate custom security attributes definitions, 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

Tip

Steps in this article might vary slightly based on the portal you start from.

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 Microsoft Entra admin center as a Attribute Definition Administrator.

  2. Browse to Protection > Custom security attributes.

  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 Microsoft Entra admin center.

  5. When finished, click Add.

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

Add a custom security attribute definition

  1. Sign in to the Microsoft Entra admin center as a Attribute Definition Administrator.

  2. Browse to Protection > Custom security attributes.

  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 attribute definitions 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 Microsoft Entra admin center.

  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.

  11. If Only allow predefined values to be assigned is Yes, click Add value to add predefined values.

    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 New attribute pane with Add predefined value pane in Microsoft Entra admin center.

  12. When finished, click Save.

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

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

Edit a custom security attribute definition

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

  1. Sign in to the Microsoft Entra admin center as a Attribute Definition Administrator.

  2. Browse to Protection > Custom security attributes.

  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 select 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.

    Screenshot of Add predefined value pane in Microsoft Entra admin center.

Deactivate a custom security attribute definition

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

  1. Sign in to the Microsoft Entra admin center as a Attribute Definition Administrator.

  2. Browse to Protection > Custom security attributes.

  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 or Microsoft Graph API

To manage custom security attribute definitions in your Microsoft Entra organization, you can also use PowerShell or Microsoft Graph API. The following examples manage attribute sets and custom security attribute definitions.

Get all attribute sets

The following example gets all attribute sets.

Get-MgDirectoryAttributeSet

Get-MgDirectoryAttributeSet | Format-List

Description          : Attributes for engineering team
Id                   : Engineering
MaxAttributesPerSet  : 25
AdditionalProperties : {}

Description          : Attributes for marketing team
Id                   : Marketing
MaxAttributesPerSet  : 25
AdditionalProperties : {}

Get top attribute sets

The following example gets the top attribute sets.

Get-MgDirectoryAttributeSet

Get-MgDirectoryAttributeSet -Top 10

Get attribute sets in order

The following example gets attribute sets in order.

Get-MgDirectoryAttributeSet

Get-MgDirectoryAttributeSet -Sort "Id"

Get an attribute set

The following example gets an attribute set.

  • Attribute set: Engineering

Get-MgDirectoryAttributeSet

Get-MgDirectoryAttributeSet -AttributeSetId "Engineering" | Format-List

Description          : Attributes for engineering team
Id                   : Engineering
MaxAttributesPerSet  : 25
AdditionalProperties : {[@odata.context, https://microsoftgraph.chinacloudapi.cn/v1.0/$metadata#directory/attributeSets/$entity]}

Add an attribute set

The following example adds a new attribute set.

  • Attribute set: Engineering

New-MgDirectoryAttributeSet

$params = @{
    Id = "Engineering"
    Description = "Attributes for engineering team"
    MaxAttributesPerSet = 25
}
New-MgDirectoryAttributeSet -BodyParameter $params

Id          Description                     MaxAttributesPerSet
--          -----------                     -------------------
Engineering Attributes for engineering team 25

Update an attribute set

The following example updates an attribute set.

  • Attribute set: Engineering

Update-MgDirectoryAttributeSet

$params = @{
    description = "Attributes for engineering team"
    maxAttributesPerSet = 20
}
Update-MgDirectoryAttributeSet -AttributeSetId "Engineering" -BodyParameter $params

Get all custom security attribute definitions

The following example gets all custom security attribute definitions.

Get-MgDirectoryCustomSecurityAttributeDefinition

Get-MgDirectoryCustomSecurityAttributeDefinition | Format-List

AllowedValues           :
AttributeSet            : Engineering
Description             : Target completion date
Id                      : Engineering_ProjectDate
IsCollection            : False
IsSearchable            : True
Name                    : ProjectDate
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : False
AdditionalProperties    : {}

AllowedValues           :
AttributeSet            : Engineering
Description             : Active projects for user
Id                      : Engineering_Project
IsCollection            : True
IsSearchable            : True
Name                    : Project
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : True
AdditionalProperties    : {}

AllowedValues           :
AttributeSet            : Marketing
Description             : Country where is application is used
Id                      : Marketing_AppCountry
IsCollection            : True
IsSearchable            : True
Name                    : AppCountry
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : True
AdditionalProperties    : {}

Filter custom security attribute definitions

The following examples filter custom security attribute definitions.

  • Filter: Attribute name eq 'Project' and status eq 'Available'

Get-MgDirectoryCustomSecurityAttributeDefinition

Get-MgDirectoryCustomSecurityAttributeDefinition -Filter "name eq 'Project' and status eq 'Available'" | Format-List

AllowedValues           :
AttributeSet            : Engineering
Description             : Active projects for user
Id                      : Engineering_Project
IsCollection            : True
IsSearchable            : True
Name                    : Project
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : True
AdditionalProperties    : {}
  • Filter: Attribute set eq 'Engineering' and status eq 'Available' and data type eq 'String'

Get-MgDirectoryCustomSecurityAttributeDefinition

Get-MgDirectoryCustomSecurityAttributeDefinition -Filter "attributeSet eq 'Engineering' and status eq 'Available' and type eq 'String'" | Format-List

AllowedValues           :
AttributeSet            : Engineering
Description             : Target completion date
Id                      : Engineering_ProjectDate
IsCollection            : False
IsSearchable            : True
Name                    : ProjectDate
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : False
AdditionalProperties    : {}

AllowedValues           :
AttributeSet            : Engineering
Description             : Active projects for user
Id                      : Engineering_Project
IsCollection            : True
IsSearchable            : True
Name                    : Project
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : True
AdditionalProperties    : {}

Get a custom security attribute definition

The following example gets a custom security attribute definition.

  • Attribute set: Engineering
  • Attribute: ProjectDate

Get-MgDirectoryCustomSecurityAttributeDefinition

Get-MgDirectoryCustomSecurityAttributeDefinition -CustomSecurityAttributeDefinitionId "Engineering_ProjectDate" | Format-List

AllowedValues           :
AttributeSet            : Engineering
Description             : Target completion date
Id                      : Engineering_ProjectDate
IsCollection            : False
IsSearchable            : True
Name                    : ProjectDate
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : False
AdditionalProperties    : {[@odata.context, https://microsoftgraph.chinacloudapi.cn/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]}

Add a custom security attribute definition

The following example adds a new custom security attribute definition.

  • Attribute set: Engineering
  • Attribute: ProjectDate
  • Attribute data type: String

New-MgDirectoryCustomSecurityAttributeDefinition

$params = @{
    attributeSet = "Engineering"
    description = "Target completion date"
    isCollection = $false
    isSearchable = $true
    name = "ProjectDate"
    status = "Available"
    type = "String"
    usePreDefinedValuesOnly = $false
}
New-MgDirectoryCustomSecurityAttributeDefinition -BodyParameter $params | Format-List

AllowedValues           :
AttributeSet            : Engineering
Description             : Target completion date
Id                      : Engineering_ProjectDate
IsCollection            : False
IsSearchable            : True
Name                    : ProjectDate
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : False
AdditionalProperties    : {[@odata.context, https://microsoftgraph.chinacloudapi.cn/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]}

Add a custom security attribute definition that supports multiple predefined values

The following example adds a new custom security attribute definition that supports multiple predefined values.

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute data type: Collection of Strings

New-MgDirectoryCustomSecurityAttributeDefinition

$params = @{
    attributeSet = "Engineering"
    description = "Active projects for user"
    isCollection = $true
    isSearchable = $true
    name = "Project"
    status = "Available"
    type = "String"
    usePreDefinedValuesOnly = $true
}
New-MgDirectoryCustomSecurityAttributeDefinition -BodyParameter $params | Format-List

AllowedValues           :
AttributeSet            : Engineering
Description             : Active projects for user
Id                      : Engineering_Project
IsCollection            : True
IsSearchable            : True
Name                    : Project
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : True
AdditionalProperties    : {[@odata.context, https://microsoftgraph.chinacloudapi.cn/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]}

Add a custom security attribute definition with a list of predefined values

The following example adds a new custom security attribute definition with a list of predefined values.

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute data type: Collection of Strings
  • Predefined values: Alpine, Baker, Cascade

New-MgDirectoryCustomSecurityAttributeDefinition

$params = @{
    attributeSet = "Engineering"
    description = "Active projects for user"
    isCollection = $true
    isSearchable = $true
    name = "Project"
    status = "Available"
    type = "String"
    usePreDefinedValuesOnly = $true
    allowedValues = @(
        @{
            id = "Alpine"
            isActive = $true
        }
        @{
            id = "Baker"
            isActive = $true
        }
        @{
            id = "Cascade"
            isActive = $true
        }
    )
}
New-MgDirectoryCustomSecurityAttributeDefinition -BodyParameter $params | Format-List

AllowedValues           :
AttributeSet            : Engineering
Description             : Active projects for user
Id                      : Engineering_Project
IsCollection            : True
IsSearchable            : True
Name                    : Project
Status                  : Available
Type                    : String
UsePreDefinedValuesOnly : True
AdditionalProperties    : {[@odata.context, https://microsoftgraph.chinacloudapi.cn/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]}

Update a custom security attribute definition

The following example updates a custom security attribute definition.

  • Attribute set: Engineering
  • Attribute: ProjectDate

Update-MgDirectoryCustomSecurityAttributeDefinition

$params = @{
    description = "Target completion date (YYYY/MM/DD)"
}
Update-MgDirectoryCustomSecurityAttributeDefinition -CustomSecurityAttributeDefinitionId "Engineering_ProjectDate" -BodyParameter $params

Update the predefined values for a custom security attribute definition

The following example updates the predefined values for a custom security attribute definition.

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute data type: Collection of Strings
  • Update predefined value: Baker
  • New predefined value: Skagit

Invoke-MgGraphRequest

Note

For this request, you must add the OData-Version header and assign it the value 4.01.

$params = @{
    "allowedValues@delta" = @(
        @{
            id = "Baker"
            isActive = $false
        }
        @{
            id = "Skagit"
            isActive = $true
        }
    )
}
$header = @{
    "OData-Version" = 4.01
}
Invoke-MgGraphRequest -Method PATCH -Uri "https://microsoftgraph.chinacloudapi.cn/v1.0/directory/customSecurityAttributeDefinitions/Engineering_Project5" -Headers $header -Body $params

Deactivate a custom security attribute definition

The following example deactivates a custom security attribute definition.

  • Attribute set: Engineering
  • Attribute: Project

Update-MgDirectoryCustomSecurityAttributeDefinition

$params = @{
    status = "Deprecated"
}
Update-MgDirectoryCustomSecurityAttributeDefinition -CustomSecurityAttributeDefinitionId "Engineering_ProjectDate" -BodyParameter $params

Get all predefined values

The following example gets all predefined values for a custom security attribute definition.

  • Attribute set: Engineering
  • Attribute: Project

Get-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue

Get-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue -CustomSecurityAttributeDefinitionId "Engineering_Project" | Format-List

Id                   : Skagit
IsActive             : True
AdditionalProperties : {}

Id                   : Baker
IsActive             : False
AdditionalProperties : {}

Id                   : Cascade
IsActive             : True
AdditionalProperties : {}

Id                   : Alpine
IsActive             : True
AdditionalProperties : {}

Get a predefined value

The following example gets a predefined value for a custom security attribute definition.

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine

Get-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue

Get-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue -CustomSecurityAttributeDefinitionId "Engineering_Project" -AllowedValueId "Alpine" | Format-List

Id                   : Alpine
IsActive             : True
AdditionalProperties : {[@odata.context, https://microsoftgraph.chinacloudapi.cn/v1.0/$metadata#directory/customSecurityAttributeDefinitions('Engineering_Project')/al
                       lowedValues/$entity]}

Add a predefined value

The following example adds a predefined value for a custom security attribute definition.

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

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine

New-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue

$params = @{
    id = "Alpine"
    isActive = $true
}
New-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue -CustomSecurityAttributeDefinitionId "Engineering_Project" -BodyParameter $params | Format-List

Id                   : Alpine
IsActive             : True
AdditionalProperties : {[@odata.context, https://microsoftgraph.chinacloudapi.cn/v1.0/$metadata#directory/customSecurityAttributeDefinitions('Engineering_Project')/al
                       lowedValues/$entity]}

Deactivate a predefined value

The following example deactivates a predefined value for a custom security attribute definition.

  • Attribute set: Engineering
  • Attribute: Project
  • Predefined value: Alpine

Update-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue

$params = @{
    isActive = $false
}
Update-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue -CustomSecurityAttributeDefinitionId "Engineering_Project" -AllowedValueId "Alpine" -BodyParameter $params

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 Microsoft Entra 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.

Next steps