Funções personalizadas do Azure

Artigo
11/15/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. Assim como as funções internas, você pode atribuir funções personalizadas a usuários, grupos e entidades de serviço nos escopos de grupo de gerenciamento, assinatura e grupo de recursos.

As funções personalizadas podem ser compartilhadas entre assinaturas que confiam no mesmo locatário do Microsoft Entra. Há um limite de 5.000 funções personalizadas por locatário. (Para o Microsoft Azure operado pela 21Vianet, o limite é de 2.000 funções personalizadas.) As funções personalizadas podem ser criadas usando o portal do Azure, o Azure PowerShell, a CLI do Azure ou a API REST.

Etapas para criar uma função personalizada

Aqui estão as etapas básicas para criar uma função personalizada.

Determine as permissões necessárias.

Ao criar uma função personalizada, você precisa saber as ações disponíveis para definir suas permissões. Normalmente, você começa com uma função interna existente e, em seguida, modifica-a de acordo com suas necessidades. Você adicionará as ações às Actions propriedades ou NotActions da definição de função. Se você tiver ações de dados, adicioná-las-á às DataActions propriedades ou NotDataActions .

Para obter mais informações, consulte a próxima seção Como determinar as permissões necessárias.
Decida como deseja criar a função personalizada.

Você pode criar funções personalizadas usando o portal do Azure, o Azure PowerShell, a CLI do Azure ou a API REST.
Crie a função personalizada.

A maneira mais fácil é usar o portal do Azure. Para obter etapas sobre como criar uma função personalizada usando o portal do Azure, consulte Criar ou atualizar funções personalizadas do Azure usando o portal do Azure.
Teste a função personalizada.

Depois de ter sua função personalizada, você precisa testá-la para verificar se ela funciona como esperado. Se precisar fazer ajustes mais tarde, você pode atualizar a função personalizada.

Como determinar as permissões de que precisa

O Azure tem milhares de permissões que você pode incluir em sua função personalizada. Aqui estão alguns métodos que podem ajudá-lo a determinar as permissões que você desejará adicionar à sua função personalizada:

Observe as funções internas existentes.

Talvez você queira modificar uma função existente ou combinar permissões usadas em várias funções.
Liste os serviços do Azure aos quais você deseja conceder acesso.
Determine os provedores de recursos mapeados para os serviços do Azure.

Os serviços do Azure expõem suas funcionalidades e permissões por meio de provedores de recursos. Por exemplo, o provedor de recursos Microsoft.Compute fornece recursos de máquina virtual e o provedor de recursos Microsoft.Billing fornece recursos de assinatura e cobrança. Conhecer os provedores de recursos pode ajudá-lo a restringir e determinar as permissões necessárias para sua função personalizada.

Ao criar uma função personalizada usando o portal do Azure, você também pode determinar os provedores de recursos pesquisando palavras-chave. Essa funcionalidade de pesquisa é descrita em Criar ou atualizar funções personalizadas do Azure usando o portal do Azure.
Pesquise as permissões disponíveis para encontrar as permissões que deseja incluir.

Ao criar uma função personalizada usando o portal do Azure, você pode pesquisar permissões por palavra-chave. Por exemplo, você pode pesquisar por máquina virtual ou permissões de cobrança. Você também pode baixar todas as permissões como um arquivo CSV e, em seguida, pesquisar esse arquivo. Essa funcionalidade de pesquisa é descrita em Criar ou atualizar funções personalizadas do Azure usando o portal do Azure.

Exemplo de função personalizada

A seguir mostra a aparência de uma função personalizada conforme exibida usando o Azure PowerShell no formato JSON. Essa função personalizada pode ser usada para monitorar e reiniciar máquinas virtuais.

{
  "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",
    "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/*"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}",
    "/subscriptions/{subscriptionId2}",
    "/providers/Microsoft.Management/managementGroups/{groupId1}"
  ]
}

A seguir mostra a mesma função personalizada exibida usando a CLI do Azure.

[
  {
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ],
    "description": "Can monitor and restart virtual machines.",
    "id": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleDefinitions/88888888-8888-8888-8888-888888888888",
    "name": "88888888-8888-8888-8888-888888888888",
    "permissions": [
      {
        "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/*"
        ],
        "dataActions": [],
        "notActions": [],
        "notDataActions": []
      }
    ],
    "roleName": "Virtual Machine Operator",
    "roleType": "CustomRole",
    "type": "Microsoft.Authorization/roleDefinitions"
  }
]

Propriedades da função personalizada

A tabela a seguir descreve o significado das propriedades da função personalizada.

Propriedade	Necessário	Tipo	Description
`Name` `roleName`	Sim	String	O nome para exibição da função personalizada. Embora uma definição de função seja um grupo de gerenciamento ou recurso de nível de assinatura, uma definição de função pode ser usada em várias assinaturas que compartilham o mesmo locatário do Microsoft Entra. Esse nome para exibição deve ser exclusivo no escopo do locatário do Microsoft Entra. Pode incluir letras, números, espaços e caracteres especiais. O número máximo de caracteres é 512.
`Id` `name`	Sim	String	A ID exclusiva da função personalizada. Para o Azure PowerShell e a CLI do Azure, essa ID é gerada automaticamente quando você cria uma nova função.
`IsCustom` `roleType`	Sim	String	Indica se essa é uma função personalizada. Defina como `true` ou `CustomRole` para funções personalizadas. Defina como `false` ou `BuiltInRole` para funções internas.
`Description` `description`	Sim	String	A descrição da função personalizada. Pode incluir letras, números, espaços e caracteres especiais. O número máximo de caracteres é 2048.
`Actions` `actions`	Sim	String[]	Uma matriz de cadeias de caracteres que especifica as ações do plano de controle que a função permite que sejam executadas. Para obter mais informações, consulte Ações.
`NotActions` `notActions`	Não	String[]	Uma matriz de cadeias de caracteres que especifica as ações do plano de controle que são excluídas do permitido `Actions`. Para obter mais informações, consulte NotActions.
`DataActions` `dataActions`	Não	String[]	Uma matriz de cadeias de caracteres que especifica as ações do plano de dados que a função permite que sejam executadas em seus dados dentro desse objeto. Se você criar uma função personalizada com `DataActions`o , essa função não poderá ser atribuída no escopo do grupo de gerenciamento. Para obter mais informações, consulte DataActions.
`NotDataActions` `notDataActions`	Não	String[]	Uma matriz de cadeias de caracteres que especifica as ações do plano de dados que são excluídas do permitido `DataActions`. Para obter mais informações, consulte NotDataActions.
`AssignableScopes` `assignableScopes`	Sim	String[]	Uma matriz de cadeias de caracteres que especifica os escopos que a função personalizada está disponível para atribuição. O número máximo é de `AssignableScopes` 2.000. Para obter mais informações, consulte AssignableScopes.

As cadeias de caracteres de permissão não diferenciam maiúsculas de minúsculas. Quando você cria suas funções personalizadas, a convenção é corresponder ao caso que você vê para permissões nas operações do provedor de recursos do Azure.

Permissões de carateres universais

Actions, , NotActionsDataActionse NotDataActions suportam curingas (*) para definir permissões. Um curinga (*) estende uma permissão para tudo o que corresponde à cadeia de caracteres de ação fornecida. Por exemplo, suponha que você queira adicionar todas as permissões relacionadas ao Azure Cost Management e exportações. Você pode adicionar todas estas cadeias de caracteres de ação:

Microsoft.CostManagement/exports/action
Microsoft.CostManagement/exports/read
Microsoft.CostManagement/exports/write
Microsoft.CostManagement/exports/delete
Microsoft.CostManagement/exports/run/action

Em vez de adicionar todas essas cadeias de caracteres, você pode simplesmente adicionar uma cadeia de caracteres curinga. Por exemplo, a seguinte cadeia de caracteres curinga é equivalente às cinco cadeias de caracteres anteriores. Isso também incluiria quaisquer permissões de exportação futuras que possam ser adicionadas.

Microsoft.CostManagement/exports/*

Nota

É recomendável especificar Actions e DataActions explicitar em vez de usar o caractere curinga (*). O acesso adicional e as permissões concedidas no futuro Actions ou DataActions podem ser comportamentos indesejados usando o curinga.

Quem pode criar, eliminar, atualizar ou ver uma função personalizada

Assim como as funções internas, a propriedade especifica os escopos que a AssignableScopes função está disponível para atribuição. A AssignableScopes propriedade de uma função personalizada também controla quem pode criar, excluir, atualizar ou exibir a função personalizada.

Tarefa	Ação	Descrição
Criar/excluir uma função personalizada	`Microsoft.Authorization/ roleDefinitions/write`	Os usuários que recebem essa ação em todas as `AssignableScopes` funções personalizadas podem criar (ou excluir) funções personalizadas para uso nesses escopos. Por exemplo, Proprietários e Administradores de Acesso de Usuário de grupos de gerenciamento, assinaturas e grupos de recursos.
Atualizar uma função personalizada	`Microsoft.Authorization/ roleDefinitions/write`	Os usuários que recebem essa ação em todas `AssignableScopes` as funções personalizadas podem atualizar as funções personalizadas nesses escopos. Por exemplo, Proprietários e Administradores de Acesso de Usuário de grupos de gerenciamento, assinaturas e grupos de recursos.
Exibir uma função personalizada	`Microsoft.Authorization/ roleDefinitions/read`	Os usuários que recebem essa ação em um escopo podem exibir as funções personalizadas que estão disponíveis para atribuição nesse escopo. Todas as funções incorporadas permitem que as funções personalizadas estejam disponíveis para atribuição.

Localizar atribuições de função para excluir uma função personalizada

Antes de excluir uma função personalizada, você deve remover todas as atribuições de função que usam a função personalizada. Se você tentar excluir uma função personalizada com atribuições de função, receberá a mensagem: There are existing role assignments referencing role (code: RoleDefinitionHasAssignments).

Aqui estão as etapas para ajudar a localizar as atribuições de função antes de excluir uma função personalizada:

Liste a definição de função personalizada.
Na seção AssignableScopes, obtenha os grupos de gerenciamento, assinaturas e grupos de recursos.
Itere sobre o e liste AssignableScopesas atribuições de função.
Remova as atribuições de função que usam a função personalizada.
Exclua a função personalizada.

Limites da função personalizada

A lista a seguir descreve os limites para funções personalizadas.

Cada locatário pode ter até 5000 funções personalizadas.
O Microsoft Azure operado pela 21Vianet pode ter até 2000 funções personalizadas para cada locatário.
Não é possível definir AssignableScopes para o escopo raiz ("/").
Não é possível usar curingas (*) em AssignableScopes. Esta restrição relativa aos de carateres universais ajuda a garantir que os utilizadores não conseguem obter potencialmente acesso a um âmbito ao atualizar a definição de função.
Só pode ter um caráter universal numa cadeia de ação.
Só pode definir um grupo de gestão em AssignableScopes de uma função personalizada.
O Azure Resource Manager não valida a existência do grupo de gerenciamento na definição de AssignableScopesfunção.
As funções personalizadas com DataActions não podem ser atribuídas no âmbito do grupo de gestão.
Você pode criar uma função personalizada com DataActions e um grupo de gerenciamento no AssignableScopes. Não é possível atribuir a função personalizada no próprio escopo do grupo de gerenciamento; No entanto, você pode atribuir a função personalizada no escopo das assinaturas dentro do grupo de gerenciamento. Isso pode ser útil se você precisar criar uma única função personalizada com DataActions a qual precisa ser atribuída em várias assinaturas, em vez de criar uma função personalizada separada para cada assinatura.

Para obter mais informações sobre as funções personalizadas e os grupos de gestão, veja O que são grupos de gestão do Azure?.

Formatos de entrada e saída

Para criar uma função personalizada usando a linha de comando, normalmente você usa JSON para especificar as propriedades desejadas para a função personalizada. Dependendo das ferramentas que você usa, os formatos de entrada e saída serão ligeiramente diferentes. Esta seção lista os formatos de entrada e saída, dependendo da ferramenta.

Azure PowerShell

Para criar uma função personalizada usando o Azure PowerShell, você deve fornecer a seguinte entrada.

{
  "Name": "",
  "Description": "",
  "Actions": [],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": []
}

Para atualizar uma função personalizada usando o Azure PowerShell, você deve fornecer a seguinte entrada. Observe que a Id propriedade foi adicionada.

{
  "Name": "",
  "Id": "",
  "Description": "",
  "Actions": [],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": []
}

A seguir mostra um exemplo da saída quando você lista uma função personalizada usando o Azure PowerShell e o comando ConvertTo-Json .

{
  "Name": "",
  "Id": "",
  "IsCustom": true,
  "Description": "",
  "Actions": [],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": []
}

CLI do Azure

Para criar ou atualizar uma função personalizada usando a CLI do Azure, você deve fornecer a seguinte entrada. Esse formato é o mesmo quando você cria uma função personalizada usando o Azure PowerShell.

{
  "Name": "",
  "Description": "",
  "Actions": [],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": []
}

A seguir mostra um exemplo da saída quando você lista uma função personalizada usando a CLI do Azure.

[
  {
    "assignableScopes": [],
    "description": "",
    "id": "",
    "name": "",
    "permissions": [
      {
        "actions": [],
        "dataActions": [],
        "notActions": [],
        "notDataActions": []
      }
    ],
    "roleName": "",
    "roleType": "CustomRole",
    "type": "Microsoft.Authorization/roleDefinitions"
  }
]

API REST

Para criar ou atualizar uma função personalizada usando a API REST, você deve fornecer a seguinte entrada. Esse formato é o mesmo que é gerado quando você cria uma função personalizada usando o portal do Azure.

{
  "properties": {
    "roleName": "",
    "description": "",
    "assignableScopes": [],
    "permissions": [
      {
        "actions": [],
        "notActions": [],
        "dataActions": [],
        "notDataActions": []
      }
    ]
  }
}

A seguir mostra um exemplo da saída quando você lista uma função personalizada usando a API REST.

{
    "properties": {
        "roleName": "",
        "type": "CustomRole",
        "description": "",
        "assignableScopes": [],
        "permissions": [
            {
                "actions": [],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ],
        "createdOn": "",
        "updatedOn": "",
        "createdBy": "",
        "updatedBy": ""
    },
    "id": "",
    "type": "Microsoft.Authorization/roleDefinitions",
    "name": ""
}