在 Azure Active Directory 中使用 PowerShell 分配具有资源范围的自定义角色Assign custom roles with resource scope using PowerShell in Azure Active Directory

本文介绍如何在 Azure Active Directory (Azure AD) 中创建组织范围的角色分配。This article describes how to create a role assignment at organization-wide scope in Azure Active Directory (Azure AD). 在组织范围分配角色会跨 Azure AD 组织授予访问权限。Assigning a role at organization-wide scope grants access across the Azure AD organization. 若要创建范围为单一 Azure AD 资源的角色分配,请参阅如何创建自定义角色并在资源范围内进行分配。本文使用 Azure Active Directory PowerShell 版本 2 模块。To create a role assignment with a scope of a single Azure AD resource, see How to create a custom role and assign it at resource scope.This article uses the Azure Active Directory PowerShell Version 2 module.

有关 Azure AD 管理员角色的详细信息,请参阅在 Azure Active Directory 中分配管理员角色For more information about Azure AD admin roles, see Assigning administrator roles in Azure Active Directory.

所需的权限Required permissions

连接到 Azure AD 组织,使用全局管理员帐户分配或删除角色。Connect to your Azure AD organization using a global administrator account to assign or remove roles.

准备 PowerShellPrepare PowerShell

安装 PowerShell 库中的 Azure AD PowerShell 模块。Install the Azure AD PowerShell module from the PowerShell Gallery. 然后使用以下命令导入 Azure AD PowerShell 预览版模块:Then import the Azure AD PowerShell preview module, using the following command:

import-module azureadpreview

若要验证该模块是否可供使用,请将以下命令返回的版本与此处列出的版本之一进行匹配:To verify that the module is ready to use, match the version returned by the following command to the one listed here:

get-module azureadpreview
  ModuleType Version      Name                         ExportedCommands
  ---------- ---------    ----                         ----------------
  Binary     2.0.0.115    azureadpreview               {Add-AzureADMSAdministrati...}

现在可以开始使用模块中的 cmdlet 了。Now you can start using the cmdlets in the module. 有关 AzureAD 模块中 cmdlet 的完整说明,请参阅 Azure AD 预览版模块的联机参考文档。For a full description of the cmdlets in the Azure AD module, see the online reference documentation for Azure AD preview module.

将角色分配给具有资源范围的用户或服务主体Assign a role to a user or service principal with resource scope

  1. 打开 Azure AD 预览版 PowerShell 模块。Open the Azure AD preview PowerShell module.
  2. 通过执行 Connect-AzureAD -AzureEnvironmentName AzureChinaCloud 命令登录。Sign in by executing the command Connect-AzureAD -AzureEnvironmentName AzureChinaCloud.
  3. 使用以下 PowerShell 脚本创建新角色。Create a new role using the following PowerShell script.
## Assign a role to a user or service principal with resource scope
# Get the user and role definition you want to link
$user = Get-AzureADUser -Filter "userPrincipalName eq 'cburl@f128.info'"
$roleDefinition = Get-AzureADMSRoleDefinition -Filter "displayName eq 'Application Support Administrator'"

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

# Create a scoped role assignment
$roleAssignment = New-AzureADMSRoleAssignment -ResourceScope $resourceScope -RoleDefinitionId $roleDefinition.Id -PrincipalId $user.objectId

若要将角色分配给服务主体而不是用户,请使用 Get-AzureADMSServicePrincipal cmdletTo assign the role to a service principal instead of a user, use the Get-AzureADMSServicePrincipal cmdlet.

在 RoleDefinition 上的操作Operations on RoleDefinition

角色定义对象包含内置角色或自定义角色的定义,以及通过该角色分配授予的权限。Role definition objects contain the definition of the built-in or custom role, along with the permissions that are granted by that role assignment. 此资源显示自定义角色定义和内置 directoryRoles(以 roleDefinition 等效形式显示)。This resource displays both custom role definitions and built-in directoryRoles (which are displayed in roleDefinition equivalent form). 现在,Azure AD 组织最多可以定义 30 个唯一的自定义 RoleDefinition。Today, an Azure AD organization can have a maximum of 30 unique custom RoleDefinitions defined.

在 RoleDefinition 上的创建操作Create Operations on RoleDefinition

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

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

# Create new custom admin role
$customAdmin = New-AzureADMSRoleDefinition -RolePermissions $rolePermissions -DisplayName $displayName -Description $description -TemplateId $templateId -IsEnabled $true

在 RoleDefinition 上的读取操作Read Operations on RoleDefinition

# Get all role definitions
Get-AzureADMSRoleDefinitions

# Get single role definition by objectId
Get-AzureADMSRoleDefinition -Id 86593cfc-114b-4a15-9954-97c3494ef49b

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

在 RoleDefinition 上的更新操作Update Operations on RoleDefinition

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

在 RoleDefinition 上的删除操作Delete operations on RoleDefinition

# Delete role definition
Remove-AzureADMSRoleDefinitions -Id c4e39bd9-1100-46d3-8c65-fb160da0071f

在 RoleAssignment 上的操作Operations on RoleAssignment

角色分配包含将给定安全主体(用户或应用程序服务主体)链接到角色定义的信息。Role assignments contain information linking a given security principal (a user or application service principal) to a role definition. 必要时,可以为分配的权限添加单一 Azure AD 资源范围。If required, you can add a scope of a single Azure AD resource for the assigned permissions. 内置角色和自定义角色支持限制权限的范围。Restricting the scope of permissions is supported for built-in and custom roles.

在 RoleAssignment 上的创建操作Create Operations on RoleAssignment

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

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

# Create a scoped role assignment
$roleAssignment = New-AzureADMSRoleAssignment -ResourceScope $resourceScope -RoleDefinitionId $roleDefinition.Id -PrincipalId $user.objectId

在 RoleAssignment 上的读取操作Read Operations on RoleAssignment

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

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

在 RoleAssignment 上进行的删除操作Delete Operations on RoleAssignment

# Delete role assignment
Remove-AzureADMSRoleAssignment -Id 'qiho4WOb9UKKgng_LbPV7tvKaKRCD61PkJeKMh7Y458-1'

后续步骤Next steps