Atribuir funções do Azure usando modelos do Azure Resource Manager

O RBAC (controle de acesso baseado em função) do Azure é o sistema de autorização usado para gerenciar o acesso aos recursos no Azure. Para conceder acesso, você atribui funções a usuários, grupos, entidades de serviço ou identidades gerenciadas em um determinado escopo. Além de usar o Azure PowerShell ou a CLI do Azure, você pode atribuir funções usando modelos do Gerenciador de Recursos do Azure. Os modelos poderão ser úteis se você precisar implantar recursos de maneira consistente e repetida. Este artigo descreve como atribuir funções usando modelos.

Observação

O Bicep é uma nova linguagem para definir os seus recursos do Azure. Ele tem uma experiência de criação mais simples do que o JSON, juntamente com outros recursos que ajudam a aprimorar a qualidade da sua infraestrutura como código. Recomendamos que qualquer pessoa nova na infraestrutura como código no Azure use o Bicep em vez de JSON.

Para saber mais sobre como definir atribuições de função usando o Bicep, confira Criar recursos do RBAC do Azure usando o Bicep. Para obter um exemplo de início rápido, confira Início Rápido: atribuir uma função do Azure usando o Bicep.

Pré-requisitos

Para atribuir funções do Azure, você precisa ter:

• Microsoft.Authorization/roleAssignments/write permissões, como Administrador de Controle de Acesso Baseado em Função ou Administrador de Acesso de Usuário

Você deve usar as versões a seguir:

• 2018-09-01-preview ou posterior para atribuir uma função do Azure a uma nova entidade de serviço
• 2020-04-01-preview ou posterior para atribuir uma função do Azure no escopo do recurso
• 2022-04-01 é a primeira versão estável

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

Obter IDs de objeto

Para atribuir uma função, você precisa especificar a ID do usuário, grupo ou aplicativo ao qual deseja atribuir a função. A ID tem o formato: 11111111-1111-1111-1111-111111111111. Você pode obter a ID usando o portal do Azure, o Azure PowerShell ou a CLI do Azure.

Usuário

Para obter a ID de um usuário, você pode usar os comandos Get-AzADUser ou az ad user show.

$objectid = (Get-AzADUser -DisplayName "{name}").id

objectid=$(az ad user show --id "{email}" --query id --output tsv)

Grupo

Para obter a ID de um grupo, você pode usar os comandos Get-AzADGroup ou az ad group show.

$objectid = (Get-AzADGroup -DisplayName "{name}").id

objectid=$(az ad group show --group "{name}" --query id --output tsv)

Identidades gerenciadas

Para obter a ID de uma identidade gerenciada, você pode usar os comandos Get-AzAdServiceprincipal ou az ad sp.

$objectid = (Get-AzADServicePrincipal -DisplayName <Azure resource name>).id

objectid=$(az ad sp list --display-name <Azure resource name> --query [].id --output tsv)

Aplicativo

Para obter a ID de uma entidade de serviço (identidade usada por um aplicativo), você pode usar os comandos Get-AzADServicePrincipal ou az ad sp list. Para uma entidade de serviço, use a ID de objeto, e não a ID do aplicativo.

$objectid = (Get-AzADServicePrincipal -DisplayName "{name}").id

objectid=$(az ad sp list --display-name "{name}" --query [].id --output tsv)

Atribuir uma função do Azure

No RBAC do Azure, para conceder acesso, você atribui uma função.

Escopo do grupo de recursos (sem parâmetros)

O modelo a seguir mostra uma maneira básica de adicionar uma atribuição de função. Alguns valores são especificados no modelo. O modelo a seguir demonstra:

• Como atribuir a função de Leitor a um usuário, grupo ou aplicativo em um escopo de grupo de recursos

Para usar o modelo, você deve fazer o seguinte:

• Criar um arquivo JSON e copiar o modelo
• Substituir <your-principal-id> pela ID de um usuário, grupo, identidade gerenciada ou aplicativo ao qual atribuir a função

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2022-04-01",
            "name": "[guid(resourceGroup().id)]",
            "properties": {
                "roleDefinitionId": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]",
                "principalId": "<your-principal-id>"
            }
        }
    ]
}

Aqui estão exemplos dos comandos New-AzResourceGroupDeployment e az deployment group create para saber como iniciar a implantação em um grupo de recursos chamado ExampleGroup.

New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup -TemplateFile rbac-test.json

az deployment group create --resource-group ExampleGroup --template-file rbac-test.json

Confira a seguir um exemplo de atribuição de função de Leitor a um usuário em um grupo de recursos após a implantação do modelo.

Escopo de grupo de recursos ou assinatura

O modelo anterior não é muito flexível. O modelo a seguir usa parâmetros e pode ser usado em diferentes escopos. O modelo a seguir demonstra:

• Como atribuir uma função a um usuário, grupo ou aplicativo em um escopo de grupo de recursos ou assinatura
• Como especificar as funções de Proprietário, Colaborador e Leitor como um parâmetro

Para usar o modelo, você deve especificar as seguintes entradas:

• A ID de um usuário, grupo, identidade gerenciada ou aplicativo ao qual atribuir a função
• Uma ID exclusiva que será usada para a atribuição de função, ou você poderá usar a ID padrão

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "principalId": {
            "type": "string",
            "metadata": {
                "description": "The principal to assign the role to"
            }
        },
        "builtInRoleType": {
            "type": "string",
            "allowedValues": [
                "Owner",
                "Contributor",
                "Reader"
            ],
            "metadata": {
                "description": "Built-in role to assign"
            }
        },
        "roleNameGuid": {
            "type": "string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "A new GUID used to identify the role assignment"
            }
        }
    },
    "variables": {
        "Owner": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
        "Contributor": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
        "Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]"
    },
    "resources": [
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2022-04-01",
            "name": "[parameters('roleNameGuid')]",
            "properties": {
                "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
                "principalId": "[parameters('principalId')]"
            }
        }
    ]
}

Observação

Esse modelo não é idempotente, a menos que o mesmo valor de roleNameGuid seja fornecido como um parâmetro para cada implantação do modelo. Se nenhum roleNameGuid for fornecido, por padrão, um novo GUID será gerado em cada implantação, e implantações subsequentes falharão com um erro Conflict: RoleAssignmentExists.

O escopo da atribuição de função é determinado no nível da implantação. Aqui estão exemplos dos comandos New-AzResourceGroupDeployment e az deployment group create para saber como iniciar a implantação em um escopo do grupo de recursos.

New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup -TemplateFile rbac-test.json -principalId $objectid -builtInRoleType Reader

az deployment group create --resource-group ExampleGroup --template-file rbac-test.json --parameters principalId=$objectid builtInRoleType=Reader

Aqui estão exemplos dos comandos New-AzDeployment and az deployment sub create para saber como iniciar a implantação em um escopo de assinatura e especificar o local.

New-AzDeployment -Location centralus -TemplateFile rbac-test.json -principalId $objectid -builtInRoleType Reader

az deployment sub create --location centralus --template-file rbac-test.json --parameters principalId=$objectid builtInRoleType=Reader

Escopo do recurso

Se você precisar atribuir uma função no nível de um recurso, defina a propriedade scope na atribuição de função como o nome do recurso.

O modelo a seguir demonstra:

• Como criar uma nova conta de armazenamento
• Como atribuir uma função a um usuário, grupo ou aplicativo no escopo da conta de armazenamento
• Como especificar as funções de Proprietário, Colaborador e Leitor como um parâmetro

Para usar o modelo, você deve especificar as seguintes entradas:

• A ID de um usuário, grupo, identidade gerenciada ou aplicativo ao qual atribuir a função

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "principalId": {
            "type": "string",
            "metadata": {
                "description": "The principal to assign the role to"
            }
        },
        "builtInRoleType": {
            "type": "string",
            "allowedValues": [
                "Owner",
                "Contributor",
                "Reader"
            ],
            "metadata": {
                "description": "Built-in role to assign"
            }
        },
        "roleNameGuid": {
            "type": "string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "A new GUID used to identify the role assignment"
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]"
        }
    },
    "variables": {
        "Owner": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
        "Contributor": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
        "Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]",
        "storageName": "[concat('storage', uniqueString(resourceGroup().id))]"
    },
    "resources": [
        {
            "apiVersion": "2019-04-01",
            "type": "Microsoft.Storage/storageAccounts",
            "name": "[variables('storageName')]",
            "location": "[parameters('location')]",
            "sku": {
                "name": "Standard_LRS"
            },
            "kind": "Storage",
            "properties": {}
        },
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2022-04-01",
            "name": "[parameters('roleNameGuid')]",
            "scope": "[concat('Microsoft.Storage/storageAccounts', '/', variables('storageName'))]",
            "dependsOn": [
                "[variables('storageName')]"
            ],
            "properties": {
                "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
                "principalId": "[parameters('principalId')]"
            }
        }
    ]
}

Para implantar o modelo anterior, use os comandos de grupo de recursos. Aqui estão exemplos dos comandos New-AzResourceGroupDeployment e az deployment group create para saber como iniciar a implantação em um escopo de recurso.

New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup -TemplateFile rbac-test.json -principalId $objectid -builtInRoleType Contributor

az deployment group create --resource-group ExampleGroup --template-file rbac-test.json --parameters principalId=$objectid builtInRoleType=Contributor

Confira a seguir um exemplo de atribuição de função de Colaborador a um usuário para uma conta de armazenamento depois de implantar o modelo.

Nova entidade de serviço

Se você criar uma entidade de serviço e tentar atribuir uma função imediatamente a essa entidade de serviço, essa atribuição de função poderá falhar em alguns casos. Por exemplo, se você criar uma identidade gerenciada e, em seguida, tentar atribuir uma função a essa entidade no mesmo modelo do Azure Resource Manager, a atribuição de função poderá falhar. Provavelmente, o motivo dessa falha é um atraso de 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 tenha replicado a entidade de serviço.

Para resolver esse cenário, você deve definir a propriedade principalType como ServicePrincipal ao criar a atribuição de função. Você também deve definir o apiVersion da atribuição de função para 2018-09-01-preview ou posterior. 2022-04-01 é a primeira versão estável.

O modelo a seguir demonstra:

• Como criar uma entidade de serviço de identidade gerenciada
• Como especificar o principalType
• Como atribuir a função de Colaborador a essa entidade de serviço em um escopo de grupo de recursos

Para usar o modelo, você deve especificar as seguintes entradas:

• O nome de base da identidade gerenciada, ou você pode usar a cadeia de caracteres padrão

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "baseName": {
            "type": "string",
            "defaultValue": "msi-test"
        }
    },
    "variables": {
        "identityName": "[concat(parameters('baseName'), '-bootstrap')]",
        "bootstrapRoleAssignmentId": "[guid(concat(resourceGroup().id, 'contributor'))]",
        "contributorRoleDefinitionId": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]"
    },
    "resources": [
        {
            "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
            "name": "[variables('identityName')]",
            "apiVersion": "2018-11-30",
            "location": "[resourceGroup().location]"
        },
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2022-04-01",
            "name": "[variables('bootstrapRoleAssignmentId')]",
            "dependsOn": [
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
            ],
            "properties": {
                "roleDefinitionId": "[variables('contributorRoleDefinitionId')]",
                "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName')), '2018-11-30').principalId]",
                "principalType": "ServicePrincipal"
            }
        }
    ]
}

Aqui estão exemplos dos comandos New-AzResourceGroupDeployment e az deployment group create para saber como iniciar a implantação em um escopo do grupo de recursos.

New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup2 -TemplateFile rbac-test.json

az deployment group create --resource-group ExampleGroup2 --template-file rbac-test.json

Confira a seguir um exemplo da atribuição de função de Colaborador para uma nova entidade de serviço de identidade gerenciada após a implantação do modelo.

Próximas etapas

• Guia de início rápido: criar e implantar modelos ARM usando o portal do Azure
• Noções básicas de estrutura e sintaxe dos modelos ARM
• Criar grupos de recursos e recursos no nível da assinatura
• Modelos de Início Rápido do Azure