Funções personalizadas do AzureAzure custom roles

Importante

A adição de um grupo de gerenciamento a AssignableScopes está em versão prévia no momento.Adding a management group to AssignableScopes is currently in preview. 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.This preview version is provided without a service level agreement, and it's not recommended for production workloads. Alguns recursos podem não ter suporte ou podem ter restrição de recursos.Certain features might not be supported or might have constrained capabilities. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

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.If the Azure built-in roles don't meet the specific needs of your organization, you can create your own custom roles. Assim como as funções internas, você pode atribuir funções personalizadas a usuários, grupos e entidades de serviço em escopos grupo de gerenciamento, assinatura e grupo de recursos.Just like built-in roles, you can assign custom roles to users, groups, and service principals at management group, subscription, and resource group scopes.

As funções personalizadas podem ser compartilhadas entre assinaturas que confiam no mesmo diretório do Azure AD.Custom roles can be shared between subscriptions that trust the same Azure AD directory. Há um limite de 5.000 funções personalizadas por diretório.There is a limit of 5,000 custom roles per directory. (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.(For Azure Germany and Azure China 21Vianet, the limit is 2,000 custom roles.) Custom roles can be created using the Azure portal, Azure PowerShell, Azure CLI, or the REST API.

Etapas para criar uma função personalizadaSteps to create a custom role

Aqui estão as etapas básicas para criar uma função personalizada.Here are the basic steps to create a custom role.

  1. Determine as permissões necessárias.Determine the permissions you need.

    Ao criar uma função personalizada, você precisa saber as operações que estão disponíveis para definir suas permissões.When you create a custom role, you need to know the operations that are available to define your permissions. Normalmente, você começa com uma função interna existente e depois a modifica conforme suas necessidades.Typically, you start with an existing built-in role and then modify it for your needs. Você adicionará as operações às Actions Propriedades ou NotActions da definição de função.You will add the operations to the Actions or NotActions properties of the role definition. Se houver operações de dados, você as adicionará às DataActions Propriedades ou NotDataActions .If you have data operations, you will add those to the DataActions or NotDataActions properties.

    Para obter mais informações, consulte a próxima seção como determinar as permissões necessárias.For more information, see the next section How to determine the permissions you need.

  2. Decida como você deseja criar a função personalizada.Decide how you want to create the custom role.

    Você pode criar funções personalizadas usando portal do Azure, Azure PowerShell, CLI do Azureou a API REST.You can create custom roles using Azure portal, Azure PowerShell, Azure CLI, or the REST API.

  3. Crie a função personalizada.Create the custom role.

    A maneira mais fácil é usar o portal do Azure.The easiest way is to use the Azure portal. Para obter 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.For steps on how to create a custom role using the Azure portal, see Create or update Azure custom roles using the Azure portal.

  4. Teste a função personalizada.Test the custom role.

    Quando tiver sua função personalizada, será necessário testá-la para verificar se funciona como o esperado.Once you have your custom role, you have to test it to verify that it works as you expect. Se você precisar fazer ajustes mais tarde, você pode atualizar a função personalizada.If you need to make adjustments later, you can update the custom role.

Como determinar as permissões que você precisaHow to determine the permissions you need

O Azure tem milhares de permissões que podem ser potencialmente incluídas em sua função personalizada.Azure has thousands of permissions that you can potentially include in your custom role. Aqui estão alguns métodos que podem ajudá-lo a determinar as permissões que você deseja adicionar à sua função personalizada:Here are some methods that can help you determine the permissions you will want to add to your custom role:

  • Examine as funções internasexistentes.Look at existing built-in roles.

    Talvez você queira modificar uma função existente ou combinar as permissões usadas em várias funções.You might want to modify an existing role or combine permissions used in multiple roles.

  • Lista os serviços do Azure aos quais você deseja conceder acesso.List the Azure services you want to grant access to.

  • Determine os provedores de recursos que são mapeados para os serviços do Azure.Determine the resource providers that map to the Azure services.

    Os serviços do Azure expõem sua funcionalidade e permissões por meio de provedores de recursos.Azure services expose their functionality and permissions through resource providers. 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.For example, the Microsoft.Compute resource provider supplies virtual machine resources and the Microsoft.Billing resource provider supplies subscription and billing resources. Conhecer os provedores de recursos pode ajudá-lo a restringir e determinar as permissões necessárias para sua função personalizada.Knowing the resource providers can help you narrow down and determine the permissions you need for your custom role.

    Ao criar uma função personalizada usando o portal do Azure, você também pode determinar os provedores de recursos pesquisando palavras-chave.When you create a custom role using the Azure portal, you can also determine the resource providers by searching for keywords. Essa funcionalidade de pesquisa é descrita em criar ou atualizar funções personalizadas do Azure usando o portal do Azure.This search functionality is described in Create or update Azure custom roles using the Azure portal.

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

  • Pesquise as permissões disponíveis para localizar as permissões que você deseja incluir.Search the available permissions to find permissions you want to include.

    Ao criar uma função personalizada usando o portal do Azure, você pode procurar permissões por palavra-chave.When you create a custom role using the Azure portal, you can search for permissions by keyword. Por exemplo, você pode pesquisar por máquina virtual ou permissões de cobrança .For example, you can search for virtual machine or billing permissions. Você também pode baixar todas as permissões como um arquivo CSV e, em seguida, pesquisar esse arquivo.You can also download all of the permissions as a CSV file and then search this file. Essa funcionalidade de pesquisa é descrita em criar ou atualizar funções personalizadas do Azure usando o portal do Azure.This search functionality is described in Create or update Azure custom roles using the Azure portal.

    Adicionar lista de permissões

Exemplo de função personalizadaCustom role example

O exemplo a seguir mostra a aparência de uma função personalizada, conforme exibido usando Azure PowerShell no formato JSON.The following shows what a custom role looks like as displayed using Azure PowerShell in JSON format. Essa função personalizada pode ser usada para monitorar e reiniciar máquinas virtuais.This custom role can be used for monitoring and restarting virtual machines.

{
  "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 seguinte mostra a mesma função personalizada que é exibida usando CLI do Azure.The following shows the same custom role as displayed using Azure CLI.

[
  {
    "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"
  }
]

Quando você cria uma função personalizada, ela aparece no portal do Azure com um ícone de recurso laranja.When you create a custom role, it appears in the Azure portal with an orange resource icon.

Ícone personalizado da função

Propriedades da função personalizadaCustom role properties

A tabela a seguir descreve o significado das propriedades da função personalizada.The following table describes what the custom role properties mean.

PropriedadeProperty ObrigatórioRequired TypeType DescriçãoDescription
Name
roleName
SimYes StringString O nome de exibição da função personalizada.The display name of the custom role. 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 diretório do AD do Azure.While a role definition is a management group or subscription-level resource, a role definition can be used in multiple subscriptions that share the same Azure AD directory. Esse nome de exibição precisa ser exclusivo no escopo do diretório do Azure AD.This display name must be unique at the scope of the Azure AD directory. Pode incluir letras, números, espaços e caracteres especiais.Can include letters, numbers, spaces, and special characters. O número máximo de caracteres é 128.Maximum number of characters is 128.
Id
name
SimYes StringString A ID exclusiva da função personalizada.The unique ID of the custom role. Para o Azure PowerShell e a CLI do Azure, essa ID é gerada automaticamente ao criar uma nova função.For Azure PowerShell and Azure CLI, this ID is automatically generated when you create a new role.
IsCustom
roleType
SimYes StringString Indica se esta é uma função personalizada.Indicates whether this is a custom role. Defina como true ou CustomRole para funções personalizadas.Set to true or CustomRole for custom roles. Defina como false ou BuiltInRole para funções internas.Set to false or BuiltInRole for built-in roles.
Description
description
SimYes StringString A descrição da função personalizada.The description of the custom role. Pode incluir letras, números, espaços e caracteres especiais.Can include letters, numbers, spaces, and special characters. O número máximo de caracteres é 1024.Maximum number of characters is 1024.
Actions
actions
SimYes String[]String[] Uma matriz de cadeias de caracteres que especifica as operações de gerenciamento permitidas pela função.An array of strings that specifies the management operations that the role allows to be performed. Para obter mais informações, consulte Ações.For more information, see Actions.
NotActions
notActions
NãoNo String[]String[] Uma matriz de cadeias de caracteres que especifica as operações de gerenciamento que são excluídas do Actions permitido.An array of strings that specifies the management operations that are excluded from the allowed Actions. Para obter mais informações, consulte NotActions.For more information, see NotActions.
DataActions
dataActions
NãoNo String[]String[] Uma matriz de cadeias de caracteres que especifica as operações de dados permitidas pela função em seus dados dentro desse objeto.An array of strings that specifies the data operations that the role allows to be performed to your data within that object. Se você criar uma função personalizada com DataActions , essa função não poderá ser atribuída ao escopo do grupo de gerenciamento.If you create a custom role with DataActions, that role cannot be assigned at the management group scope. Para obter mais informações, consulte Dataactions.For more information, see DataActions.
NotDataActions
notDataActions
NãoNo String[]String[] Uma matriz de cadeias de caracteres que especifica as operações de dados excluídas do DataActions permitido.An array of strings that specifies the data operations that are excluded from the allowed DataActions. Para obter mais informações, consulte NotDataActions.For more information, see NotDataActions.
AssignableScopes
assignableScopes
SimYes String[]String[] Uma matriz de cadeias de caracteres que especifica os escopos para os quais a função personalizada está disponível para atribuição.An array of strings that specifies the scopes that the custom role is available for assignment. Você só pode definir um grupo de gerenciamento em AssignableScopes uma função personalizada.You can only define one management group in AssignableScopes of a custom role. A adição de um grupo de gerenciamento a AssignableScopes está em versão prévia no momento.Adding a management group to AssignableScopes is currently in preview. Para obter mais informações, consulte AssignableScopes.For more information, see AssignableScopes.

Permissões de curingaWildcard permissions

Actions, NotActions , DataActions e NotDataActions suportam curingas ( * ) para definir permissões.Actions, NotActions, DataActions, and NotDataActions support wildcards (*) to define permissions. Um curinga ( * ) estende uma permissão para tudo que corresponde à cadeia de caracteres de ação que você fornece.A wildcard (*) extends a permission to everything that matches the action string you provide. Por exemplo, suponha que você quisesse adicionar todas as permissões relacionadas ao gerenciamento de custos e às exportações do Azure.For example, suppose that you wanted to add all the permissions related to Azure Cost Management and exports. Você pode adicionar todas essas cadeias de caracteres de ação:You could add all of these action strings:

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.Instead of adding all of these strings, you could just add a wildcard string. Por exemplo, a cadeia curinga a seguir é equivalente às cinco cadeias de caracteres anteriores.For example, the following wildcard string is equivalent to the previous five strings. Isso também incluiria permissões de exportação futuras que possam ser adicionadas.This would also include any future export permissions that might be added.

Microsoft.CostManagement/exports/*

Você também pode ter vários curingas em uma cadeia de caracteres.You can also have multiple wildcards in a string. Por exemplo, a cadeia de caracteres a seguir representa todas as permissões de consulta para o gerenciamento de custos.For example, the following string represents all query permissions for Cost Management.

Microsoft.CostManagement/*/query/*

Quem pode criar, excluir, atualizar ou exibir uma função personalizadaWho can create, delete, update, or view a custom role

Assim como funções internas, a propriedade AssignableScopes especifica os escopos para os quais a função está disponível para atribuição.Just like built-in roles, the AssignableScopes property specifies the scopes that the role is available for assignment. A propriedade AssignableScopes de uma função personalizada também controla quem pode criar, excluir, atualizar ou exibir a função personalizada.The AssignableScopes property for a custom role also controls who can create, delete, update, or view the custom role.

TarefaTask OperaçãoOperation DescriçãoDescription
Criar/excluir uma função personalizadaCreate/delete a custom role 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.Users that are granted this operation on all the AssignableScopes of the custom role can create (or delete) custom roles for use in those scopes. Por exemplo, proprietários e Administradores de acesso de usuário de grupos de gerenciamento, assinaturas e grupos de recursos.For example, Owners and User Access Administrators of management groups, subscriptions, and resource groups.
Atualizar uma função personalizadaUpdate a custom role 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.Users that are granted this operation on all the AssignableScopes of the custom role can update custom roles in those scopes. Por exemplo, proprietários e Administradores de acesso de usuário de grupos de gerenciamento, assinaturas e grupos de recursos.For example, Owners and User Access Administrators of management groups, subscriptions, and resource groups.
Exibir uma função personalizadaView a custom role 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.Users that are granted this operation at a scope can view the custom roles that are available for assignment at that scope. Todas as funções internas permitem que as funções personalizadas sejam disponibilizadas para atribuição.All built-in roles allow custom roles to be available for assignment.

Limites de função personalizadaCustom role limits

A lista a seguir descreve os limites para funções personalizadas.The following list describes the limits for custom roles.

  • Cada diretório pode ter até 5000 funções personalizadas.Each directory can have up to 5000 custom roles.
  • O Azure Alemanha e o Azure China 21Vianet podem ter até 2000 funções personalizadas para cada diretório.Azure Germany and Azure China 21Vianet can have up to 2000 custom roles for each directory.
  • Não é possível definir AssignableScopes como o escopo raiz ( "/" ).You cannot set AssignableScopes to the root scope ("/").
  • Não é possível usar curingas ( * ) em AssignableScopes .You cannot use wildcards (*) in 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.This wildcard restriction helps ensure a user can't potentially obtain access to a scope by updating the role definition.
  • Você só pode definir um grupo de gerenciamento em AssignableScopes uma função personalizada.You can only define one management group in AssignableScopes of a custom role. A adição de um grupo de gerenciamento a AssignableScopes está em versão prévia no momento.Adding a management group to AssignableScopes is currently in preview.
  • Funções personalizadas com DataActions não podem ser atribuídas no escopo do grupo de gerenciamento.Custom roles with DataActions cannot be assigned at the management group scope.
  • Azure Resource Manager não valida a existência do grupo de gerenciamento no escopo atribuível da definição de função.Azure Resource Manager doesn't validate the management group's existence in the role definition's assignable scope.

Para obter mais informações sobre funções personalizadas e grupos de gerenciamento, consulte organizar seus recursos com grupos de gerenciamento do Azure.For more information about custom roles and management groups, see Organize your resources with Azure management groups.

Formatos de entrada e saídaInput and output formats

Para criar uma função personalizada usando a linha de comando, você normalmente usa o JSON para especificar as propriedades desejadas para a função personalizada.To create a custom role using the command line, you typically use JSON to specify the properties you want for the custom role. Dependendo das ferramentas usadas, os formatos de entrada e saída terão uma aparência ligeiramente diferente.Depending on the tools you use, the input and output formats will look slightly different. Esta seção lista os formatos de entrada e saída, dependendo da ferramenta.This section lists the input and output formats depending on the tool.

Azure PowerShellAzure PowerShell

Para criar uma função personalizada usando Azure PowerShell, você deve fornecer a entrada a seguir.To create a custom role using Azure PowerShell, you must provide following input.

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

Para atualizar uma função personalizada usando Azure PowerShell, você deve fornecer a entrada a seguir.To update a custom role using Azure PowerShell, you must provide the following input. Observe que a Id propriedade foi adicionada.Note that the Id property has been added.

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

Veja a seguir um exemplo de saída quando você lista uma função personalizada usando Azure PowerShell e o comando ConvertTo-JSON .The following shows an example of the output when you list a custom role using Azure PowerShell and the ConvertTo-Json command.

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

CLI do AzureAzure CLI

Para criar ou atualizar uma função personalizada usando CLI do Azure, você deve fornecer a entrada a seguir.To create or update a custom role using Azure CLI, you must provide following input. Esse formato é o mesmo formato quando você cria uma função personalizada usando Azure PowerShell.This format is the same format when you create a custom role using Azure PowerShell.

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

Veja a seguir um exemplo de saída ao listar uma função personalizada usando CLI do Azure.The following shows an example of the output when you list a custom role using Azure CLI.

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

API RESTREST API

Para criar ou atualizar uma função personalizada usando a API REST, você deve fornecer a entrada a seguir.To create or update a custom role using the REST API, you must provide following input. Esse formato é o mesmo formato que é gerado quando você cria uma função personalizada usando o portal do Azure.This format is the same format that gets generated when you create a custom role using the Azure portal.

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

Veja a seguir um exemplo de saída quando você lista uma função personalizada usando a API REST.The following shows an example of the output when you list a custom role using the REST API.

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

Próximas etapasNext steps