在 Microsoft Entra 中添加或停用自定义安全属性定义
Microsoft Entra ID 中的自定义安全属性是特定于业务的属性（键值对），你可以定义这些属性并将其分配给 Microsoft Entra 对象。 本文介绍如何添加、编辑或停用自定义安全属性定义。
先决条件
要添加或停用自定义安全属性定义，你必须具有：
- 属性定义管理员角色
- 使用 Microsoft Graph PowerShell 时需要 Microsoft.Graph 模块
- 使用 Azure AD PowerShell 时具有 AzureADPreview 版本 2.0.2.138 或更高版本
重要
默认情况下，全局管理员和其他管理员角色无权读取、定义或分配自定义安全属性。
添加属性集
提示
本文中的步骤可能因开始使用的门户而略有不同。
属性集是相关属性的集合。 所有自定义安全属性都必须是属性集的一部分。 不能重命名或删除属性集。
以属性定义管理员身份登录到 Microsoft Entra 管理中心。
浏览到“保护”>“自定义安全属性”。
单击“添加属性集”添加一个新的属性集。
如果“添加属性集”处于禁用状态，请确保你已分配有“属性定义管理员”角色。 有关详细信息，请参阅对自定义安全属性进行故障排除。
输入属性的名称、说明和最大数量。
属性集名称可以是 32 个字符，没有空格或特殊字符。 一旦你指定了一个名称，就不能对它重命名。 有关详细信息，请参阅限制和约束。
完成后，单击“添加”。
新属性集随即显示在属性集列表中。
添加自定义安全属性定义
以属性定义管理员身份登录到 Microsoft Entra 管理中心。
浏览到“保护”>“自定义安全属性”。
在“自定义安全属性”页上，查找现有属性集或单击“添加属性集”以添加新的属性集。
所有自定义安全属性定义都必须是属性集的一部分。
单击以打开所选的属性集。
单击“添加属性”，将新的自定义安全属性添加到属性集。
在“属性名称”框中，输入一个自定义安全属性名称。
自定义安全属性名称可以有 32 个字符，不能使用空格或特殊字符。 一旦你指定了一个名称，就不能对它重命名。 有关详细信息，请参阅限制和约束。
在“说明”框中，输入一个可选的说明。
说明的长度可以是 128 个字符。 如果需要，稍后可以更改说明。
在“数据类型”列表中，选择自定义安全属性的数据类型。
数据类型 说明 Boolean 可为 true、True、false 或 False 的布尔值。 Integer 32 位整数。 字符串 长度可以为 X 个字符的字符串。 为“允许分配多个值”选择“是”或“否”。
如果选择“是”，则允许将多个值分配给此自定义安全属性。 如果选择“否”，则仅允许将单个值分配给此自定义安全属性。
为“仅允许分配预定义值”，选择“是”或“否”。
如果选择“是”，则要求从预定义值列表中为此自定义安全属性分配值。 如果选择“否”，则允许为此自定义安全属性分配用户定义的值或可能的预定义值。
如果“仅允许分配预定义值”为“是”，请单击“添加值”以添加预定义值。
活动的值可用于分配给对象。 处于非活动状态的值即使已定义，也无法用于分配。
完成后，单击“保存”。
新的自定义安全属性随即出现在自定义安全属性列表中。
如果要包含预定义值，请按照下一节中的步骤操作。
编辑自定义安全属性定义
在添加新的自定义安全属性定义后，可以稍后编辑某些属性。 有些属性是不可变的，无法更改。
以属性定义管理员身份登录到 Microsoft Entra 管理中心。
浏览到“保护”>“自定义安全属性”。
单击包含要编辑的自定义安全属性的属性集。
在自定义安全属性列表中，单击要编辑的自定义安全属性对应的省略号，然后选择“编辑属性”。
编辑已启用的属性。
如果“仅允许分配预定义值”为“是”，请单击“添加值”以添加预定义值。 单击现有的预定义值以更改“是否处于活动状态?”设置。
停用自定义安全属性定义
一旦添加了自定义安全属性定义，便无法将其删除。 但是，可以停用自定义安全属性定义。
以属性定义管理员身份登录到 Microsoft Entra 管理中心。
浏览到“保护”>“自定义安全属性”。
单击包含要停用的自定义安全属性的属性集。
在自定义安全属性列表中，在你要停用的自定义安全属性旁边添加一个复选标记。
单击“停用属性”。
在出现的“停用属性”对话框中，单击“是”。
自定义安全属性将被停用并移至“已停用的属性”列表。
PowerShell 或 Microsoft Graph API
要在 Microsoft Entra 组织中管理自定义安全属性定义，还可以使用 PowerShell 或 Microsoft Graph API。 以下示例管理属性集和自定义安全属性定义。
获取所有属性集
以下示例获取所有属性集。
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-MgDirectoryAttributeSet -Top 10
按顺序获取属性集
以下示例按顺序获取属性集。
Get-MgDirectoryAttributeSet -Sort "Id"
获取一个属性集
以下示例获取某个属性集。
- 属性集：
Engineering
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]}
添加属性集
以下示例添加新的属性集。
- 属性集：
Engineering
$params = @{
Id = "Engineering"
Description = "Attributes for engineering team"
MaxAttributesPerSet = 25
}
New-MgDirectoryAttributeSet -BodyParameter $params
Id Description MaxAttributesPerSet
-- ----------- -------------------
Engineering Attributes for engineering team 25
更新属性集
以下示例更新属性集。
- 属性集：
Engineering
Update-MgDirectoryAttributeSet
$params = @{
description = "Attributes for engineering team"
maxAttributesPerSet = 20
}
Update-MgDirectoryAttributeSet -AttributeSetId "Engineering" -BodyParameter $params
获取全部自定义安全属性定义
以下示例获取所有自定义安全属性定义。
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 : {}
筛选自定义安全属性定义
以下示例筛选自定义安全属性定义。
- 筛选条件：属性名称为“Project”且状态为“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 : {}
- 筛选条件：属性集为“Engineering”，状态为“Available”且数据类型为“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 : {}
获取自定义安全属性定义
以下示例获取自定义安全属性定义。
- 属性集：
Engineering - 属性：
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]}
添加自定义安全属性定义
以下示例添加新的自定义安全属性定义。
- 属性集：
Engineering - 属性：
ProjectDate - 属性数据类型：字符串
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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]}
添加可支持多个预定义值的自定义安全属性定义
以下示例添加支持多个预定义值的新自定义安全属性定义。
- 属性集：
Engineering - 属性：
Project - 属性数据类型：字符串集合
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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]}
添加包含预定义值列表的自定义安全属性定义
以下示例添加新的自定义安全属性定义，其中包含预定义值的列表。
- 属性集：
Engineering - 属性：
Project - 属性数据类型：字符串集合
- 预定义值：
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://graph.microsoft.com/v1.0/$metadata#directory/customSecurityAttributeDefinitions/$entity]}
更新自定义安全属性定义
以下示例更新自定义安全属性定义。
- 属性集：
Engineering - 属性：
ProjectDate
Update-MgDirectoryCustomSecurityAttributeDefinition
$params = @{
description = "Target completion date (YYYY/MM/DD)"
}
Update-MgDirectoryCustomSecurityAttributeDefinition -CustomSecurityAttributeDefinitionId "Engineering_ProjectDate" -BodyParameter $params
更新自定义安全属性定义的预定义值
以下示例更新自定义安全属性定义的预定义值。
- 属性集：
Engineering - 属性：
Project - 属性数据类型：字符串集合
- 更新预定义值：
Baker - 新建预定义值：
Skagit
注意
对于此请求，必须添加 OData-Version 标头，并为其分配值 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
停用自定义安全属性定义
以下示例停用自定义安全属性定义。
- 属性集：
Engineering - 属性：
Project
Update-MgDirectoryCustomSecurityAttributeDefinition
$params = @{
status = "Deprecated"
}
Update-MgDirectoryCustomSecurityAttributeDefinition -CustomSecurityAttributeDefinitionId "Engineering_ProjectDate" -BodyParameter $params
获取所有预定义值
以下示例获取自定义安全属性定义的所有预定义值。
- 属性集：
Engineering - 属性：
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 : {}
获取一个预定义值
以下示例获取自定义安全属性定义的某个预定义值。
- 属性集：
Engineering - 属性：
Project - 预定义值：
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]}
添加预定义值
以下示例添加自定义安全属性定义的某个预定义值。
可以为将 usePreDefinedValuesOnly 设置为 true 的自定义安全属性添加预定义值。
- 属性集：
Engineering - 属性：
Project - 预定义值：
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]}
停用预定义值
以下示例停用自定义安全属性定义的某个预定义值。
- 属性集：
Engineering - 属性：
Project - 预定义值：
Alpine
Update-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue
$params = @{
isActive = $false
}
Update-MgDirectoryCustomSecurityAttributeDefinitionAllowedValue -CustomSecurityAttributeDefinitionId "Engineering_Project" -AllowedValueId "Alpine" -BodyParameter $params
常见问题
能否删除自定义安全属性定义？
不能，无法删除自定义安全属性定义。 只能停用自定义安全属性定义。 停用自定义安全属性后，它将不再能够应用于 Microsoft Entra 对象。 为已停用的自定义安全属性定义分配的自定义安全属性不会被自动删除。 对已停用的自定义安全属性的数量没有限制。 每个租户可以有 500 个活动的自定义安全属性定义，每个自定义安全属性定义可以有 100 个预定义值。