Funções personalizadas do Azure

Se as funções internas do Azure não atenderem às necessidades específicas de sua organização, você poderá criar funções personalizadas próprias. Assim como as funções internas, é possível atribuir funções personalizadas a usuários, grupos e entidades de serviço no gerenciamento de grupo, assinatura e nos escopos de 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.

  1. Determinar as permissões necessárias.

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

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

  2. Decida como você deseja criar a função personalizada.

    Crie funções personalizadas usando o portal do Azure, Azure PowerShell, a CLI do Azure ou a API REST.

  3. Criar a função personalizada.

    A maneira mais fácil é usar o portal do Azure. Para ver as 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.

  4. Testar a função personalizada.

    Quando tiver sua função personalizada, será necessário testá-la para verificar se funciona como o esperado. Se você precisar fazer ajustes mais tarde, você pode atualizar a função personalizada.

Como determinar as permissões necessárias

O Azure tem milhares de permissões que podem ser incluídas na função personalizada. Confira alguns métodos que podem ajudá-lo a determinar as permissões que deseja adicionar à função personalizada:

  • Examine as funções internas existentes.

    Talvez você queira modificar uma função existente ou combinar as 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 que mapeiam para os serviços do Azure.

    Os serviços do Azure expõem sua funcionalidade 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 assinatura e recursos de 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 por palavras-chave. Essa funcionalidade de pesquisa é descrita em Criar ou atualizar funções personalizadas do Azure usando o portal do Azure.

    Add permissions pane with resource provider

  • Pesquise as permissões disponíveis para encontrar as permissões que quer incluir.

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

    Add permissions list

Exemplo de função personalizada

A seguir, mostra como uma função personalizada se parece, conforme exibida no formato JSON usando o Azure PowerShell. 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}"
  ]
}

O exemplo a seguir mostra a mesma função personalizada exibida usando 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 que as propriedades de funções personalizadas significam.

Propriedade Obrigatório Tipo Descrição
Name
roleName
Sim String O nome de 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 de 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 ao criar uma nova função.
IsCustom
roleType
Sim String Indica se esta é uma função personalizada. Defina como true ou CustomRole para funções personalizadas. Definia para 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 permitidas pela função. Para obter mais informações, confira Ações.
NotActions
notActions
Não String[] Uma matriz de cadeias de caracteres que especifica as ações do painel de controle excluídas do Actions permitido. 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 DataActionso , 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 excluídas do DataActions permitido. Para obter mais informações, consulte NotDataActions.
AssignableScopes
assignableScopes
Sim String[] Uma matriz de cadeias de caracteres que especifica os escopos para os quais a função personalizada está disponível para atribuição. O número máximo de AssignableScopes é 2000. 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 é que as maiúsculas e minúsculas mostradas sejam correspondentes para as permissões nas operações do provedor de recursos do Azure.

Permissões curinga

Actions, NotActions, DataActions e NotDataActions suportam curingas (*) para definir permissões. Um curinga (*) estende uma permissão para tudo que corresponde à cadeia de caracteres de ação que você fornece. Por exemplo, suponha que você quisesse adicionar todas as permissões relacionadas ao Gerenciamento de Custos do Azure e a 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, basta adicionar uma cadeia de caracteres curinga. Por exemplo, a cadeia de caracteres curinga a seguir é equivalente às cinco cadeias de caracteres anteriores. Isso também inclui futuras permissões de exportação que possam ser adicionadas.

Microsoft.CostManagement/exports/*

Observação

É recomendável que você especifique Actions e DataActions explicitamente, em vez de usar o caractere curinga (*). O acesso adicional e as permissões concedidas por meio de Actions ou DataActions futuros podem ser um comportamento indesejado ao usar o curinga.

Quem pode criar, excluir, atualizar ou exibir uma função personalizada

Assim como funções internas, a propriedade AssignableScopes especifica os escopos para os quais a função está disponível para atribuição. A propriedade AssignableScopes 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 todos os AssignableScopes da função personalizada podem criar (ou excluir) funções personalizadas para uso nesses escopos. Por exemplo, os Proprietários e os Administradores de Acesso do Usuário de grupo 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 todos os AssignableScopes da função personalizada podem atualizar as funções personalizadas nesses escopos. Por exemplo, os Proprietários e os Administradores de Acesso do Usuário de grupo 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 ver as funções personalizadas que estão disponíveis para atribuição nesse escopo. Todas as funções internas permitem que as funções personalizadas sejam disponibilizadas 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 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 encontrar as atribuições de função antes de excluir uma função personalizada:

Limite de Funções personalizadas

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 como o escopo raiz ("/").
  • Não é possível usar curingas (*) em AssignableScopes. Essa restrição de curinga ajuda a garantir que um usuário não possa obter acesso a um escopo atualizando a definição de função.
  • Você pode ter apenas um curinga em uma cadeia de caracteres de ação.
  • Você só pode definir um grupo de gerenciamento 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 função AssignableScopes.
  • Funções personalizadas com DataActions não podem ser atribuídas no escopo do grupo de gerenciamento.
  • 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 funções personalizadas e grupos de gerenciamento, confira O que são grupos de gerenciamento do Azure?.

Formatos de entrada e saída

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

PowerShell do Azure

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

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

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

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

Veja a seguir um exemplo de 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 entrada a seguir. Esse formato é o mesmo formato quando você cria uma função personalizada usando o Azure PowerShell.

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

Veja a seguir um exemplo de saída ao listar 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 entrada a seguir. Esse formato é o mesmo formato gerado quando você cria uma função personalizada usando o portal do Azure.

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

Veja a seguir um exemplo de saída ao listar 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": ""
}

Próximas etapas