在 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 總管的必要條件。
將目錄角色指派給具有資源範圍的用戶或服務主體
執行 命令
Connect-MgGraph
來登入。使用下列 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'
下一步
- 在 Microsoft Entra 系統管理角色論壇上 與我們分享
- 如需角色和 Microsoft Entra 系統管理員角色指派的詳細資訊,請參閱 指派系統管理員角色
- 如需默認用戶權力,請參閱 預設來賓和成員用戶權力的比較