Atribuir funções personalizadas com escopo de recursos usando o PowerShell no Microsoft Entra ID

  • Artigo

Este artigo descreve como criar uma atribuição de função em todo o escopo da organização no Microsoft Entra ID. A atribuição de uma função ao nível da organização concede acesso transversal a toda a organização do Microsoft Entra. Para criar uma atribuição de função com um escopo de um único recurso do Microsoft Entra, consulte Criar e atribuir uma função personalizada no Microsoft Entra ID. Este artigo usa o módulo SDK do Microsoft Graph PowerShell.

Para obter mais informações sobre as funções do Microsoft Entra, consulte Funções internas do Microsoft Entra.

Pré-requisitos

  • Licença do Microsoft Entra ID P1 ou P2
  • Administrador de Função com Privilégios ou Administrador Global
  • Módulo do Microsoft Graph PowerShell ao usar o PowerShell

Para obter mais informações, consulte Pré-requisitos para usar o PowerShell ou o Graph Explorer.

Atribuir uma função de diretório a um usuário ou entidade de serviço com escopo de recurso

  1. Carregue o módulo PowerShell do Microsoft Graph.

  2. Entre executando o comando Connect-MgGraph.

  3. Crie uma nova função usando o seguinte script do 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

Para atribuir a função a uma entidade de serviço em vez de a um usuário, use o cmdlet Get-MgServicePrincipal .

Definições de função

Os objetos de definição de função contêm a definição da função interna ou personalizada, juntamente com as permissões concedidas por essa atribuição de função. Este recurso exibe definições de função personalizadas e funções de diretório internas (que são exibidas no formulário equivalente a roleDefinition). Para obter informações sobre o número máximo de funções personalizadas que podem ser criadas em uma organização do Microsoft Entra, consulte Limites e restrições de serviço do Microsoft Entra.

Criar uma definição de função

# 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

Ler e listar definições de função

# 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'"

Atualizar uma definição de função

# 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"

Excluir uma definição de função

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

Atribuições de funções

As atribuições de função contêm informações que vinculam uma determinada entidade de segurança (uma entidade de serviço de usuário ou aplicativo) a uma definição de função. Se necessário, você pode adicionar um escopo de um único recurso do Microsoft Entra para as permissões atribuídas. A restrição do escopo de uma atribuição de função é suportada para funções internas e personalizadas.

Criar uma atribuição de função

# 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

Ler e listar atribuições de função

# 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'"

Remover uma atribuição de função

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

Próximos passos