Atribuir funções do Azure com a API REST

O controlo de acesso baseado em funções do Azure (RBAC do Azure) é o sistema de autorização que utiliza para gerir 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 com a API REST.

Pré-requisitos

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

Tem de utilizar 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 um novo principal de serviço

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

Atribuir uma função do Azure

Para atribuir uma função, utilize as Atribuições de Funções – Criar API REST e especifique o principal de segurança, a definição de função e o âmbito. Para chamar esta API, tem de ter acesso à ação Microsoft.Authorization/roleAssignments/write . Das funções incorporadas, apenas o Proprietário e o Administrador de Acesso de Utilizadores têm acesso a esta ação.

  1. Utilize a API REST De Definições de Função – Listar ou veja Funções incorporadas para obter o identificador da definição de função que pretende atribuir.

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

  3. Comece com o seguinte pedido 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 âmbito da atribuição de função.

    Âmbito Tipo
    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 Recurso

    No exemplo anterior, microsoft.web é um fornecedor de recursos que se refere a uma instância Serviço de Aplicações. Da mesma forma, pode utilizar outros fornecedores de recursos e especificar o âmbito. Para obter mais informações, veja Fornecedores e tipos de recursos do Azure e operações suportadas do fornecedor de recursos do Azure.

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

  6. No corpo do pedido, substitua {scope} pelo mesmo âmbito que no URI.

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

  8. Substitua {principalId} pelo identificador de objeto do utilizador, grupo ou principal de serviço ao qual será atribuída a função.

O seguinte pedido e corpo atribui a função Leitor de Cópias de Segurança a um utilizador no âmbito da subscrição:

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}"
  }
}

Segue-se um exemplo do resultado:

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

Novo principal de serviço

Se criar um novo principal de serviço e tentar atribuir imediatamente uma função a esse principal de serviço, essa atribuição de função pode falhar em alguns casos. Por exemplo, se criar uma nova identidade gerida e, em seguida, tentar atribuir uma função a esse principal de serviço, a atribuição de função poderá falhar. O motivo para esta falha é provavelmente um atraso na replicação. O principal de serviço é criado numa região; No entanto, a atribuição de função pode ocorrer numa região diferente que ainda não tenha replicado o principal de serviço.

Para resolver este cenário, utilize as Atribuições de Funções – Criar API REST e defina a principalType propriedade como ServicePrincipal. Também tem de definir como apiVersion2018-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"
  }
}

Passos seguintes