Atribuir funções do Azure com a API REST

O controle de acesso baseado em função do Azure (Azure RBAC) é o sistema de autorização que você usa para gerenciar o acesso aos recursos do Azure. Para conceder acesso, atribua funções a utilizadores, grupos, principais de serviço ou identidades geridas num determinado âmbito. Este artigo descreve como atribuir funções usando a API REST.

Pré-requisitos

Para atribuir funções do Azure, tem de ter:

Você deve usar as seguintes versões:

  • 2015-07-01 ou posterior para atribuir uma função do Azure
  • 2018-09-01-preview ou posterior para atribuir uma função do Azure a uma nova entidade de serviço

Para obter mais informações, consulte Versões de API das APIs REST do RBAC do Azure.

Atribuir uma função do Azure

Para atribuir uma função, use a API Atribuições de Função - Criar REST e especifique a entidade de segurança, a definição de função e o escopo. Para chamar essa API, você deve ter acesso à ação, como Administrador de Controle de Acesso Baseado em Microsoft.Authorization/roleAssignments/write Função.

  1. Use a API REST de Definições de Função - Lista ou consulte Funções internas para obter o identificador da definição de função que você deseja atribuir.

  2. Use uma ferramenta GUID para gerar um identificador exclusivo que será usado para o identificador de atribuição de função. O identificador tem o formato: 00000000-0000-0000-0000-000000000000

  3. Comece com a seguinte solicitação e corpo:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId}?api-version=2022-04-01
    
    {
      "properties": {
        "roleDefinitionId": "/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
        "principalId": "{principalId}"
      }
    }
    
  4. No URI, substitua {scope} pelo escopo da atribuição de função.

    Âmbito Type
    providers/Microsoft.Management/managementGroups/{groupId1} Grupo de gestão
    subscriptions/{subscriptionId1} Subscrição
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1 Grupo de recursos
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1/providers/microsoft.web/sites/mysite1 Resource

    No exemplo anterior, microsoft.web é um provedor de recursos que se refere a uma instância do Serviço de Aplicativo. Da mesma forma, você pode usar quaisquer outros provedores de recursos e especificar o escopo. Para obter mais informações, consulte Provedores e tipos de recursos do Azure e operações de provedor de recursos do Azure com suporte.

  5. Substitua {roleAssignmentId} pelo identificador GUID da atribuição de função.

  6. No corpo da solicitação, substitua {scope} pelo mesmo escopo do URI.

  7. Substitua {roleDefinitionId} pelo identificador de definição de função.

  8. Substitua {principalId} pelo identificador de objeto do usuário, grupo ou entidade de serviço à qual será atribuída a função.

A solicitação e o corpo a seguir atribuem a função Leitor de Backup a um usuário no escopo da assinatura:

PUT https://management.azure.com/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId1}?api-version=2022-04-01
{
  "properties": {
    "roleDefinitionId": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleDefinitions/a795c7a0-d4a2-40c1-ae25-d81f01202912",
    "principalId": "{objectId1}"
  }
}

A seguir mostra um exemplo da saída:

{
    "properties": {
        "roleDefinitionId": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleDefinitions/a795c7a0-d4a2-40c1-ae25-d81f01202912",
        "principalId": "{objectId1}",
        "principalType": "User",
        "scope": "/subscriptions/{subscriptionId1}",
        "condition": null,
        "conditionVersion": null,
        "createdOn": "2022-05-06T23:55:23.7679147Z",
        "updatedOn": "2022-05-06T23:55:23.7679147Z",
        "createdBy": null,
        "updatedBy": "{updatedByObjectId1}",
        "delegatedManagedIdentityResourceId": null,
        "description": null
    },
    "id": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId1}",
    "type": "Microsoft.Authorization/roleAssignments",
    "name": "{roleAssignmentId1}"
}

Nova entidade de serviço

Se você criar uma nova entidade de serviço e tentar atribuir imediatamente uma função a essa entidade de serviço, essa atribuição de função poderá falhar em alguns casos. Por exemplo, se você criar uma nova identidade gerenciada e, em seguida, tentar atribuir uma função a essa entidade de serviço, a atribuição de função poderá falhar. A razão para essa falha é provavelmente um atraso na replicação. A entidade de serviço é criada em uma região; no entanto, a atribuição de função pode ocorrer em uma região diferente que ainda não replicou a entidade de serviço.

Para resolver esse cenário, use Atribuições de função - Criar API REST e defina a principalType propriedade como ServicePrincipal. Você também deve definir o apiVersion para 2018-09-01-preview ou posterior. 2022-04-01 é a primeira versão estável.

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId}?api-version=2022-04-01
{
  "properties": {
    "roleDefinitionId": "/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "principalId": "{principalId}",
    "principalType": "ServicePrincipal"
  }
}

Próximos passos