共用方式為

在 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 或 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 Directory 服務限制和局限 (部分機器翻譯)。

建立角色定義

# 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 00000000-0000-0000-0000-000000000000

# 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 'aaaaaaaa-bbbb-cccc-1111-222222222222'"

# Get role assignments for a given role definition 
Get-MgRoleManagementDirectoryRoleAssignment -Filter "RoleDefinitionId eq '00000000-0000-0000-0000-000000000000'"

移除角色指派

# Remove role assignment
Remove-MgRoleManagementDirectoryRoleAssignment -UnifiedRoleAssignmentId 'aB1cD2eF3gH4iJ5kL6-mN7oP8qR-1'

下一步