Funções personalizadas do Azure

Importante

A adição de um grupo de gerenciamento a AssignableScopes está em versão prévia no momento. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft 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 grupo de gerenciamento, na assinatura e nos escopos de grupo de recursos.

As funções personalizadas podem ser compartilhadas entre assinaturas que confiam no mesmo diretório do Microsoft Azure AD. Há um limite de 5.000 funções personalizadas por diretório. (Para Azure Alemanha e Azure China 21Vianet, o limite é de 2.000 funções personalizadas.) As funções personalizadas podem ser criadas usando o portal do Azure, Azure PowerShell, 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 operaçõ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 operações às propriedades Actions ou NotActions da definição de função. Se você tiver operaçõ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.

    Adicionar o painel de permissões com o provedor de recursos

  • 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.

    Lista Adicionar permissões

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 Type Descrição
Name
roleName
Sim String O nome de exibição da função personalizada. Embora a definição de função seja um recurso no nível da assinatura ou grupo de gerenciamento, ela pode ser usada em várias assinaturas que compartilham o mesmo diretório do Microsoft Azure AD. Esse nome de exibição precisa ser exclusivo no escopo do diretório do Azure AD. Pode incluir letras, números, espaços e caracteres especiais. O número máximo de caracteres é 128.
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 é 1024.
Actions
actions
Sim String[] Uma matriz de cadeias de caracteres que especifica as operações de gerenciamento permitidas pela função. Para obter mais informações, consulte Ações.
NotActions
notActions
Não String[] Uma matriz de cadeias de caracteres que especifica as operações de gerenciamento que são 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 operações de dados permitidas pela função em seus dados dentro desse objeto. Se você criar uma função personalizada com DataActions, ela 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 operações 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. Você só pode definir um grupo de gerenciamento em AssignableScopes de uma função personalizada. A adição de um grupo de gerenciamento a AssignableScopes está em versão prévia no momento. 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/*

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 Operação Descrição
Criar/excluir uma função personalizada Microsoft.Authorization/ roleDefinitions/write Os usuários que recebem essa operaçã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 operaçã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 operação em um escopo podem exibir 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.

Limite de Funções personalizadas

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

  • Cada diretório pode ter até 5 mil funções personalizadas.
  • O Azure Alemanha e o Azure China 21Vianet podem ter até 2 mil funções personalizadas para cada diretó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ê só pode definir um grupo de gerenciamento em AssignableScopes de uma função personalizada. A adição de um grupo de gerenciamento a AssignableScopes está em versão prévia no momento.
  • Você pode ter apenas um curinga em uma cadeia de caracteres de ação.
  • Funções personalizadas com DataActions não podem ser atribuídas no escopo do grupo de gerenciamento.
  • O Azure Resource Manager não valida a existência do grupo de gerenciamento no escopo atribuível da definição de função.

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.

Azure PowerShell

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