在 Microsoft Entra ID 中使用 PowerShell 指派具有資源範圍的自定義角色

  • 發行項

本文說明如何在 Microsoft Entra ID 中，在全組織範圍內建立角色指派。 在整個組織範圍指派角色，會授與跨 Microsoft Entra 組織的存取權。 若要建立具有單一 Microsoft Entra 資源範圍的角色指派，請參閱 在 Microsoft Entra 識別符中建立和指派自定義角色。 本文使用 Microsoft Graph PowerShell SDK 模組。

如需 Microsoft Entra 角色的詳細資訊，請參閱 Microsoft Entra 內建角色。

必要條件

  • Microsoft Entra ID P1 或 P2 授權
  • 特殊權限角色管理員或全域管理員
  • 使用 PowerShell 時的 Microsoft Graph PowerShell 模組

如需詳細資訊，請參閱 使用PowerShell或 Graph 總管的必要條件。

將目錄角色指派給具有資源範圍的用戶或服務主體

  1. 載入 Microsoft Graph PowerShell 模組。

  2. 執行 命令 Connect-MgGraph來登入。

  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'

下一步