在 Microsoft Entra ID 中使用 PowerShell 分配具有资源范围的自定义角色

  • 项目

本文介绍如何在 Microsoft Entra ID 中创建组织范围的角色分配。 在组织范围分配角色会跨 Microsoft Entra 组织授予访问权限。 若要创建范围为一个 Microsoft Entra 资源的角色分配，请参阅在 Microsoft Entra ID 中创建和分配自定义角色。 本文使用 Microsoft Graph PowerShell SDK 模块。

有关 Microsoft Entra 角色的详细信息，请参阅 Microsoft Entra 内置角色。

先决条件

  • Microsoft Entra ID P1 或 P2 许可证
  • 特权角色管理员或全局管理员
  • 使用 PowerShell 时的 Microsoft Graph PowerShell 模块

有关详细信息，请参阅使用 PowerShell 的先决条件。

将目录角色分配给具有资源范围的用户或服务主体

  1. 加载 Microsoft Graph PowerShell 模块。

  2. 通过执行 Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' 命令登录。

  3. 使用以下 PowerShell 脚本创建新角色。

    ## Assign a role to a user or service principal with resource scope
# Get the user and role definition you want to link
$user = Get-MgUser -Filter "UserPrincipalName eq 'cburl@f128.info'"
$roleDefinition = Get-MgRoleManagementDirectoryRoleDefinition -Filter "DisplayName eq 'Application Support Administrator'"

# Get app registration and construct resource scope for assignment.
$appRegistration = Get-MgApplication -Filter "displayName eq 'f/128 Filter Photos'"
$directoryScope = '/' + $appRegistration.Id

# Create a scoped role assignment
$roleAssignment = New-MgRoleManagementDirectoryRoleAssignment -DirectoryScopeId $directoryScope `
   -RoleDefinitionId $roleDefinition.Id -PrincipalId $user.Id

若要将该角色分配给服务主体而不是用户，请使用 Get-MgServicePrincipal cmdlet。

角色定义

角色定义对象包含内置角色或自定义角色的定义，以及通过该角色分配授予的权限。 此资源会显示自定义角色定义和内置目录角色（以 roleDefinition 等效形式显示）。 若要了解可在 Microsoft Entra 组织中创建的自定义角色数量上限，请参阅 Microsoft Entra 服务限制。

创建角色定义

# Basic information
$description = "Can manage credentials of application registrations"
$displayName = "Application Registration Credential Administrator"
$templateId = (New-Guid).Guid

# Set of actions to include
$rolePermissions = @{
    "allowedResourceActions" = @(
        "microsoft.directory/applications/standard/read",
        "microsoft.directory/applications/credentials/update"
    )
}

# Create new custom directory role
$customAdmin = New-MgRoleManagementDirectoryRoleDefinition -RolePermissions $rolePermissions `
   -DisplayName $displayName -Description $description -TemplateId $templateId -IsEnabled:$true

读取并列出角色定义

# Get all role definitions
Get-MgRoleManagementDirectoryRoleDefinition

# Get single role definition by ID
Get-MgRoleManagementDirectoryRoleDefinition -UnifiedRoleDefinitionId 86593cfc-114b-4a15-9954-97c3494ef49b

# Get single role definition by templateId
Get-MgRoleManagementDirectoryRoleDefinition -Filter "TemplateId eq 'c4e39bd9-1100-46d3-8c65-fb160da0071f'"

更新角色定义

# Update role definition
# This works for any writable property on role definition. You can replace display name with other
# valid properties.
Update-MgRoleManagementDirectoryRoleDefinition -UnifiedRoleDefinitionId c4e39bd9-1100-46d3-8c65-fb160da0071f `
   -DisplayName "Updated DisplayName"

删除角色定义

# Delete role definition
Remove-MgRoleManagementDirectoryRoleDefinition -UnifiedRoleDefinitionId c4e39bd9-1100-46d3-8c65-fb160da0071f

角色分配

角色分配包含将给定安全主体（用户或应用程序服务主体）链接到角色定义的信息。 必要时，可以为分配的权限添加单一 Microsoft Entra 资源范围。 内置角色和自定义角色支持限制角色分配的范围。

创建角色分配

# Get the user and role definition you want to link
$user = Get-MgUser -Filter "userPrincipalName eq 'cburl@f128.info'"
$roleDefinition = Get-MgRoleManagementDirectoryRoleDefinition -Filter "DisplayName eq 'Application Support Administrator'"

# Get app registration and construct resource scope for assignment.
$appRegistration = Get-MgApplication -Filter "displayName eq 'f/128 Filter Photos'"
$directoryScope = '/' + $appRegistration.Id

# Create a scoped role assignment
$roleAssignment = New-MgRoleManagementDirectoryRoleAssignment -DirectoryScopeId $directoryScope `
   -RoleDefinitionId $roleDefinition.Id -PrincipalId $user.Id

读取并列出角色分配

# Get role assignments for a given principal
Get-MgRoleManagementDirectoryRoleAssignment -Filter "PrincipalId eq '27c8ca78-ab1c-40ae-bd1b-eaeebd6f68ac'"

# Get role assignments for a given role definition 
Get-MgRoleManagementDirectoryRoleAssignment -Filter "RoleDefinitionId eq '355aed8a-864b-4e2b-b225-ea95482e7570'"

删除角色分配

# Remove role assignment
Remove-MgRoleManagementDirectoryRoleAssignment -UnifiedRoleAssignmentId 'qiho4WOb9UKKgng_LbPV7tvKaKRCD61PkJeKMh7Y458-1'

后续步骤