Criar ou atualizar funções personalizadas do Azure usando o Azure PowerShell

Artigo
12/01/2023

Se as funções internas do Azure não atenderem às necessidades específicas da sua organização, você poderá criar suas próprias funções personalizadas. Este artigo descreve como listar, criar, atualizar ou excluir funções personalizadas usando o Azure PowerShell.

Para obter um tutorial passo a passo sobre como criar uma função personalizada, consulte Tutorial: Criar uma função personalizada do Azure usando o Azure PowerShell.

Nota

Recomendamos que utilize o módulo do Azure Az PowerShell para interagir com o Azure. Veja Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.

Pré-requisitos

Para criar funções personalizadas, você precisa:

Permissões para criar funções personalizadas, como Administrador de Acesso de Usuário
Azure Cloud Shell ou Azure PowerShell

Listar funções personalizadas

Para listar as funções disponíveis para atribuição em um escopo, use o comando Get-AzRoleDefinition . O exemplo a seguir lista todas as funções que estão disponíveis para atribuição na assinatura selecionada.

Get-AzRoleDefinition | FT Name, IsCustom

Name                                              IsCustom
----                                              --------
Virtual Machine Operator                              True
AcrImageSigner                                       False
AcrQuarantineReader                                  False
AcrQuarantineWriter                                  False
API Management Service Contributor                   False
...

O exemplo a seguir lista apenas as funções personalizadas que estão disponíveis para atribuição na assinatura selecionada.

Get-AzRoleDefinition -Custom | FT Name, IsCustom

Name                     IsCustom
----                     --------
Virtual Machine Operator     True

Se a assinatura selecionada não estiver na AssignableScopes função da função, a função personalizada não será listada.

Listar uma definição de função personalizada

Para listar uma definição de função personalizada, use Get-AzRoleDefinition. Este é o mesmo comando que você usa para uma função interna.

Get-AzRoleDefinition <role_name> | ConvertTo-Json

PS C:\> Get-AzRoleDefinition "Virtual Machine Operator" | ConvertTo-Json

{
  "Name": "Virtual Machine Operator",
  "Id": "00000000-0000-0000-0000-000000000000",
  "IsCustom": true,
  "Description": "Can monitor and restart virtual machines.",
  "Actions": [
    "Microsoft.Storage/*/read",
    "Microsoft.Network/*/read",
    "Microsoft.Compute/*/read",
    "Microsoft.Compute/virtualMachines/start/action",
    "Microsoft.Compute/virtualMachines/restart/action",
    "Microsoft.Authorization/*/read",
    "Microsoft.ResourceHealth/availabilityStatuses/read",
    "Microsoft.Resources/subscriptions/resourceGroups/read",
    "Microsoft.Insights/alertRules/*",
    "Microsoft.Support/*"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/11111111-1111-1111-1111-111111111111"
  ]
}

O exemplo a seguir lista apenas as ações da função:

(Get-AzRoleDefinition <role_name>).Actions

PS C:\> (Get-AzRoleDefinition "Virtual Machine Operator").Actions

"Microsoft.Storage/*/read",
"Microsoft.Network/*/read",
"Microsoft.Compute/*/read",
"Microsoft.Compute/virtualMachines/start/action",
"Microsoft.Compute/virtualMachines/restart/action",
"Microsoft.Authorization/*/read",
"Microsoft.ResourceHealth/availabilityStatuses/read",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Insights/alertRules/*",
"Microsoft.Insights/diagnosticSettings/*",
"Microsoft.Support/*"

Criar uma função personalizada

Para criar uma função personalizada, use o comando New-AzRoleDefinition . Há dois métodos de estruturação da função, usando PSRoleDefinition um objeto ou um modelo JSON.

Obter operações para um provedor de recursos

Ao criar funções personalizadas, é importante conhecer todas as operações possíveis dos provedores de recursos. Você pode exibir a lista de operações do provedor de recursos ou usar o comando Get-AzProviderOperation para obter essas informações. Por exemplo, se você quiser verificar todas as operações disponíveis para máquinas virtuais, use este comando:

Get-AzProviderOperation <operation> | FT OperationName, Operation, Description -AutoSize

PS C:\> Get-AzProviderOperation "Microsoft.Compute/virtualMachines/*" | FT OperationName, Operation, Description -AutoSize

OperationName                                  Operation                                                      Description
-------------                                  ---------                                                      -----------
Get Virtual Machine                            Microsoft.Compute/virtualMachines/read                         Get the propertie...
Create or Update Virtual Machine               Microsoft.Compute/virtualMachines/write                        Creates a new vir...
Delete Virtual Machine                         Microsoft.Compute/virtualMachines/delete                       Deletes the virtu...
Start Virtual Machine                          Microsoft.Compute/virtualMachines/start/action                 Starts the virtua...
...

Criar uma função personalizada com o objeto PSRoleDefinition

Ao usar o PowerShell para criar uma função personalizada, você pode usar uma das funções internas como ponto de partida ou pode começar do zero. O primeiro exemplo nesta seção começa com uma função interna e, em seguida, personaliza-a com mais permissões. Edite os atributos para adicionar o Actions, ou AssignableScopes que você deseja e, em seguida, NotActionssalve as alterações como uma nova função.

O exemplo a seguir começa com a função interna Colaborador de Máquina Virtual para criar uma função personalizada chamada Operador de Máquina Virtual. A nova função concede acesso a todas as ações de leitura dos provedores de recursos Microsoft.Compute, Microsoft.Storage e Microsoft.Network e concede acesso para iniciar, reiniciar e monitorar máquinas virtuais. A função personalizada pode ser usada em duas assinaturas.

$role = Get-AzRoleDefinition "Virtual Machine Contributor"
$role.Id = $null
$role.Name = "Virtual Machine Operator"
$role.Description = "Can monitor and restart virtual machines."
$role.Actions.Clear()
$role.Actions.Add("Microsoft.Storage/*/read")
$role.Actions.Add("Microsoft.Network/*/read")
$role.Actions.Add("Microsoft.Compute/*/read")
$role.Actions.Add("Microsoft.Compute/virtualMachines/start/action")
$role.Actions.Add("Microsoft.Compute/virtualMachines/restart/action")
$role.Actions.Add("Microsoft.Authorization/*/read")
$role.Actions.Add("Microsoft.ResourceHealth/availabilityStatuses/read")
$role.Actions.Add("Microsoft.Resources/subscriptions/resourceGroups/read")
$role.Actions.Add("Microsoft.Insights/alertRules/*")
$role.Actions.Add("Microsoft.Support/*")
$role.AssignableScopes.Clear()
$role.AssignableScopes.Add("/subscriptions/00000000-0000-0000-0000-000000000000")
$role.AssignableScopes.Add("/subscriptions/11111111-1111-1111-1111-111111111111")
New-AzRoleDefinition -Role $role

O exemplo a seguir mostra outra maneira de criar a função personalizada Operador de Máquina Virtual . Começa criando um novo PSRoleDefinition objeto. As ações são especificadas perms na variável e definidas como a Actions propriedade. A NotActions propriedade é definida lendo a NotActionsfunção interna do Colaborador da Máquina Virtual. Como o Colaborador de Máquina Virtual não tem nenhum NotActions, essa linha não é necessária, mas mostra como as informações podem ser recuperadas de outra função.

$role = [Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition]::new()
$role.Name = 'Virtual Machine Operator 2'
$role.Description = 'Can monitor and restart virtual machines.'
$role.IsCustom = $true
$perms = 'Microsoft.Storage/*/read','Microsoft.Network/*/read','Microsoft.Compute/*/read'
$perms += 'Microsoft.Compute/virtualMachines/start/action','Microsoft.Compute/virtualMachines/restart/action'
$perms += 'Microsoft.Authorization/*/read'
$perms += 'Microsoft.ResourceHealth/availabilityStatuses/read'
$perms += 'Microsoft.Resources/subscriptions/resourceGroups/read'
$perms += 'Microsoft.Insights/alertRules/*','Microsoft.Support/*'
$role.Actions = $perms
$role.NotActions = (Get-AzRoleDefinition -Name 'Virtual Machine Contributor').NotActions
$subs = '/subscriptions/00000000-0000-0000-0000-000000000000','/subscriptions/11111111-1111-1111-1111-111111111111'
$role.AssignableScopes = $subs
New-AzRoleDefinition -Role $role

Criar uma função personalizada com o modelo JSON

Um modelo JSON pode ser usado como a definição de origem para a função personalizada. O exemplo a seguir cria uma função personalizada que permite acesso de leitura a recursos de armazenamento e computação, acesso ao suporte e adiciona essa função a duas assinaturas. Crie um novo arquivo C:\CustomRoles\customrole1.json com o exemplo a seguir. O Id deve ser definido como null na criação inicial da função, pois um novo ID é gerado automaticamente.

{
  "Name": "Custom Role 1",
  "Id": null,
  "IsCustom": true,
  "Description": "Allows for read access to Azure storage and compute resources and access to support",
  "Actions": [
    "Microsoft.Compute/*/read",
    "Microsoft.Storage/*/read",
    "Microsoft.Support/*"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000",
    "/subscriptions/11111111-1111-1111-1111-111111111111"
  ]
}

Para adicionar a função às assinaturas, execute o seguinte comando do PowerShell:

New-AzRoleDefinition -InputFile "C:\CustomRoles\customrole1.json"

Atualizar uma função personalizada

Semelhante à criação de uma função personalizada, você pode modificar uma função personalizada existente usando o PSRoleDefinition objeto ou um modelo JSON.

Atualizar uma função personalizada com o objeto PSRoleDefinition

Para modificar uma função personalizada, primeiro, use o comando Get-AzRoleDefinition para recuperar a definição de função. Em segundo lugar, faça as alterações desejadas na definição da função. Finalmente, use o comando Set-AzRoleDefinition para salvar a definição de função modificada.

O exemplo a seguir adiciona a Microsoft.Insights/diagnosticSettings/* ação à função personalizada Operador de Máquina Virtual .

$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.Actions.Add("Microsoft.Insights/diagnosticSettings/*")
Set-AzRoleDefinition -Role $role

PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.Actions.Add("Microsoft.Insights/diagnosticSettings/*")
PS C:\> Set-AzRoleDefinition -Role $role

Name             : Virtual Machine Operator
Id               : 88888888-8888-8888-8888-888888888888
IsCustom         : True
Description      : Can monitor and restart virtual machines.
Actions          : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
                   Microsoft.Compute/virtualMachines/start/action...}
NotActions       : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                   /subscriptions/11111111-1111-1111-1111-111111111111}

O exemplo a seguir adiciona uma assinatura do Azure aos escopos atribuíveis da função personalizada Operador de Máquina Virtual .

Get-AzSubscription -SubscriptionName Production3

$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.AssignableScopes.Add("/subscriptions/22222222-2222-2222-2222-222222222222")
Set-AzRoleDefinition -Role $role

PS C:\> Get-AzSubscription -SubscriptionName Production3

Name     : Production3
Id       : 22222222-2222-2222-2222-222222222222
TenantId : 99999999-9999-9999-9999-999999999999
State    : Enabled

PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.AssignableScopes.Add("/subscriptions/22222222-2222-2222-2222-222222222222")
PS C:\> Set-AzRoleDefinition -Role $role

Name             : Virtual Machine Operator
Id               : 88888888-8888-8888-8888-888888888888
IsCustom         : True
Description      : Can monitor and restart virtual machines.
Actions          : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
                   Microsoft.Compute/virtualMachines/start/action...}
NotActions       : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                   /subscriptions/11111111-1111-1111-1111-111111111111,
                   /subscriptions/22222222-2222-2222-2222-222222222222}

O exemplo a seguir adiciona um grupo de gerenciamento à AssignableScopes função personalizada Operador de Máquina Virtual .

Get-AzManagementGroup

$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.AssignableScopes.Add("/providers/Microsoft.Management/managementGroups/{groupId1}")
Set-AzRoleDefinition -Role $role

PS C:\> Get-AzManagementGroup

Id          : /providers/Microsoft.Management/managementGroups/marketing-group
Type        : /providers/Microsoft.Management/managementGroups
Name        : marketing-group
TenantId    : 99999999-9999-9999-9999-999999999999
DisplayName : Marketing group

PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.AssignableScopes.Add("/providers/Microsoft.Management/managementGroups/marketing-group")
PS C:\> Set-AzRoleDefinition -Role $role

Name             : Virtual Machine Operator
Id               : 88888888-8888-8888-8888-888888888888
IsCustom         : True
Description      : Can monitor and restart virtual machines.
Actions          : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
                   Microsoft.Compute/virtualMachines/start/action...}
NotActions       : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                   /subscriptions/11111111-1111-1111-1111-111111111111,
                   /subscriptions/22222222-2222-2222-2222-222222222222,
                   /providers/Microsoft.Management/managementGroups/marketing-group}

Atualizar uma função personalizada com um modelo JSON

Usando o modelo JSON anterior, você pode modificar facilmente uma função personalizada existente para adicionar ou remover Ações. Atualize o modelo JSON e adicione a ação de leitura para rede, conforme mostrado no exemplo a seguir. As definições listadas no modelo não são aplicadas cumulativamente a uma definição existente, o que significa que a função aparece exatamente como você especifica no modelo. Você também precisa atualizar o campo Id com a ID da função. Se você não tiver certeza de qual é esse valor, poderá usar o cmdlet Get-AzRoleDefinition para obter essas informações.

{
  "Name": "Custom Role 1",
  "Id": "acce7ded-2559-449d-bcd5-e9604e50bad1",
  "IsCustom": true,
  "Description": "Allows for read access to Azure storage and compute resources and access to support",
  "Actions": [
    "Microsoft.Compute/*/read",
    "Microsoft.Storage/*/read",
    "Microsoft.Network/*/read",
    "Microsoft.Support/*"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000",
    "/subscriptions/11111111-1111-1111-1111-111111111111"
  ]
}

Para atualizar a função existente, execute o seguinte comando do PowerShell:

Set-AzRoleDefinition -InputFile "C:\CustomRoles\customrole1.json"

Eliminar uma função personalizada

Remova todas as atribuições de função que usam a função personalizada. Para obter mais informações, consulte Localizar atribuições de função para excluir uma função personalizada.

Use o comando Remove-AzRoleDefinition para excluir a função personalizada.

O exemplo a seguir remove a função personalizada Operador de Máquina Virtual .

Get-AzRoleDefinition "Virtual Machine Operator"
Get-AzRoleDefinition "Virtual Machine Operator" | Remove-AzRoleDefinition

PS C:\> Get-AzRoleDefinition "Virtual Machine Operator"

Name             : Virtual Machine Operator
Id               : 88888888-8888-8888-8888-888888888888
IsCustom         : True
Description      : Can monitor and restart virtual machines.
Actions          : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
                   Microsoft.Compute/virtualMachines/start/action...}
NotActions       : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                   /subscriptions/11111111-1111-1111-1111-111111111111}

PS C:\> Get-AzRoleDefinition "Virtual Machine Operator" | Remove-AzRoleDefinition

Confirm
Are you sure you want to remove role definition with name 'Virtual Machine Operator'.
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): Y