Skip to content

Latest commit

 

History

History
1133 lines (796 loc) · 36.9 KB

custom-security-attributes-add.md

File metadata and controls

1133 lines (796 loc) · 36.9 KB
titledescriptionauthormanagerms.authorms.servicems.subservicems.topicms.datems.collection
Add or deactivate custom security attribute definitions in Microsoft Entra ID
Learn how to add new custom security attribute definitions or deactivate custom security attribute definitions in Microsoft Entra ID.
rolyon
femila
rolyon
entra
fundamentals
how-to
11/27/2024
M365-identity-device-management

Add or deactivate custom security attribute definitions in Microsoft Entra ID

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:

[!INCLUDE security-attributes-roles]

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

  2. Browse to Entra ID > Custom security attributes.

  3. Select 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.

    :::image type="content" source="./media/custom-security-attributes-add/attribute-set-add.png" alt-text="Screenshot of New attribute set pane in Microsoft Entra admin center." lightbox="./media/custom-security-attributes-add/attribute-set-add.png":::

  5. When finished, select 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 Entra ID > Custom security attributes.

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

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

  4. Select to open the selected attribute set.

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

    :::image type="content" source="./media/custom-security-attributes-add/attribute-new.png" alt-text="Screenshot of New attribute pane in Microsoft Entra admin center." lightbox="./media/custom-security-attributes-add/attribute-new.png":::

  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 typeDescription
    BooleanA Boolean value that can be true, True, false, or False.
    IntegerA 32-bit integer.
    StringA 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, select 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.

    :::image type="content" source="./media/custom-security-attributes-add/attribute-new-value-add.png" alt-text="Screenshot of New attribute pane with Add predefined value pane in Microsoft Entra admin center." lightbox="./media/custom-security-attributes-add/attribute-new-value-add.png":::

  12. When finished, select 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 Entra ID > Custom security attributes.

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

  4. In the list of custom security attributes, select 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, select Add value to add predefined values. Select an existing predefined value to change the Is active? setting.

    :::image type="content" source="./media/custom-security-attributes-add/attribute-predefined-value-add.png" alt-text="Screenshot of Add predefined value pane in Microsoft Entra admin center." lightbox="./media/custom-security-attributes-add/attribute-predefined-value-add.png":::

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 Entra ID > Custom security attributes.

  3. Select 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. Select Deactivate attribute.

  6. In the Deactivate attribute dialog that appears, select 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 : {} 

List attributeSets

GET https://graph.microsoft.com/v1.0/directory/attributeSets

Get-AzureADMSAttributeSet

Get-AzureADMSAttributeSet

Get top attribute sets

The following example gets the top attribute sets.

Get-MgDirectoryAttributeSet

Get-MgDirectoryAttributeSet-Top 10

List attributeSets

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

None


Get attribute sets in order

The following example gets attribute sets in order.

Get-MgDirectoryAttributeSet

Get-MgDirectoryAttributeSet-Sort "Id"

List attributeSets

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

None


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://graph.microsoft.com/v1.0/$metadata#directory/attributeSets/$entity]} 

Get attributeSet

GET https://graph.microsoft.com/v1.0/directory/attributeSets/Engineering

Get-AzureADMSAttributeSet

Get-AzureADMSAttributeSet-Id "Engineering"

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 

Create attributeSet

POST https://graph.microsoft.com/v1.0/directory/attributeSets  { "id":"Engineering", "description":"Attributes for engineering team", "maxAttributesPerSet":25 }

New-AzureADMSAttributeSet

New-AzureADMSAttributeSet-Id "Engineering"-Description "Attributes for engineering team"-MaxAttributesPerSet 10

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

Update attributeSet

PATCH https://graph.microsoft.com/v1.0/directory/attributeSets/Engineering { "description":"Attributes for engineering team", "maxAttributesPerSet":20 }

Set-AzureADMSAttributeSet

Set-AzureADMSAttributeSet-Id "Engineering"-Description "Attributes for cloud engineering team"Set-AzureADMSAttributeSet-Id "Engineering"-MaxAttributesPerSet 20

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 : {} 

List customSecurityAttributeDefinitions

GET https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions

Get-AzureADMSCustomSecurityAttributeDefinition

Get-AzureADMSCustomSecurityAttributeDefinition

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 : {} 

List customSecurityAttributeDefinitions

GET https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions?$filter=name+eq+'Project'%20and%20status+eq+'Available'

None


  • 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 : {} 

List customSecurityAttributeDefinitions

GET https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions?$filter=attributeSet+eq+'Engineering'%20and%20status+eq+'Available'%20and%20type+eq+'String'

None


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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]} 

Get customSecurityAttributeDefinition

GET https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_ProjectDate

Get-AzureADMSCustomSecurityAttributeDefinition

Get-AzureADMSCustomSecurityAttributeDefinition-Id "Engineering_ProjectDate"

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=$falseisSearchable=$truename="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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]} 

Create customSecurityAttributeDefinition

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

New-AzureADMSCustomSecurityAttributeDefinition

New-AzureADMSCustomSecurityAttributeDefinition-AttributeSet "Engineering"-Name "ProjectDate"-Description "Target completion date"-Type "String"-Status "Available"-IsCollection $false-IsSearchable $true-UsePreDefinedValuesOnly $false

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=$trueisSearchable=$truename="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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]} 

Create customSecurityAttributeDefinition

POST https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions { "attributeSet":"Engineering", "description":"Active projects for user", "isCollection":true, "isSearchable":true, "name":"Project", "status":"Available", "type":"String", "usePreDefinedValuesOnly": true }

None


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=$trueisSearchable=$truename="Project"status="Available"type="String"usePreDefinedValuesOnly=$trueallowedValues=@( @{ 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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]} 

Create customSecurityAttributeDefinition

POST https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions { "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 } ] }

None


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 customSecurityAttributeDefinition

PATCH https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_ProjectDate { "description": "Target completion date (YYYY/MM/DD)", }

Set-AzureADMSCustomSecurityAttributeDefinition

Set-AzureADMSCustomSecurityAttributeDefinition-Id "Engineering_ProjectDate"-Description "Target completion date (YYYY/MM/DD)"

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://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_Project5"-Headers $header-Body $params

Update customSecurityAttributeDefinition

Note

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

PATCH https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_Project { "allowedValues@delta": [ { "id": "Baker", "isActive": false }, { "id": "Skagit", "isActive": true } ] }

None


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

Update customSecurityAttributeDefinition

PATCH https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_Project { "status": "Deprecated" }

Set-AzureADMSCustomSecurityAttributeDefinition

Set-AzureADMSCustomSecurityAttributeDefinition-Id "Engineering_Project"-Status "Deprecated"

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 : {} 

List allowedValues

GET https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_Project/allowedValues

Get-AzureADMSCustomSecurityAttributeDefinitionAllowedValue

Get-AzureADMSCustomSecurityAttributeDefinitionAllowedValue-CustomSecurityAttributeDefinitionId "Engineering_Project"

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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions('Engineering_Project')/al lowedValues/$entity]} 

Get allowedValue

GET https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_Project/allowedValues/Alpine

Get-AzureADMSCustomSecurityAttributeDefinitionAllowedValue

Get-AzureADMSCustomSecurityAttributeDefinitionAllowedValue-CustomSecurityAttributeDefinitionId "Engineering_Project"-Id "Alpine"

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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions('Engineering_Project')/al lowedValues/$entity]} 

Create allowedValue

POST https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_Project/allowedValues { "id":"Alpine", "isActive":"true" }

Add-AzureADMScustomSecurityAttributeDefinitionAllowedValues

Add-AzureADMScustomSecurityAttributeDefinitionAllowedValues-CustomSecurityAttributeDefinitionId "Engineering_Project"-Id "Alpine"-IsActive $true

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

Update allowedValue

PATCH https://graph.microsoft.com/v1.0/directory/customSecurityAttributeDefinitions/Engineering_Project/allowedValues/Alpine { "isActive":"false" }

Set-AzureADMSCustomSecurityAttributeDefinitionAllowedValue

Set-AzureADMSCustomSecurityAttributeDefinitionAllowedValue-CustomSecurityAttributeDefinitionId "Engineering_Project"-Id "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 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

close