Automatizar a adição de um usuário de laboratório a um laboratório no Azure DevTest Labs

O Azure DevTest Labs permite criar rapidamente ambientes de desenvolvimento e teste de autoatendimento usando o portal do Azure. No entanto, se você tiver várias equipes e várias instâncias do DevTest Labs, a automatização do processo de criação poderá poupar tempo. Os modelos do Azure Resource Manager permitem criar laboratórios, VMs de laboratório, imagens personalizadas e fórmulas e adicionar usuários de maneira automatizada. Este artigo se concentra especificamente na adição de usuários a uma instância do DevTest Labs.

Para adicionar um usuário a um laboratório, você adiciona o usuário à função de Usuário do DevTest Labs para o laboratório. Este artigo mostra como automatizar a adição de um usuário a um laboratório usando uma das seguintes maneiras:

• Modelos do Azure Resource Manager
• Cmdlets do Azure PowerShell
• CLI do Azure.

Usar modelos do Gerenciador de Recursos do Azure

O modelo do Resource Manager de exemplo a seguir especifica um usuário a ser adicionado à função de usuário do DevTest Labs de um laboratório.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "principalId": {
      "type": "string",
      "metadata": {
        "description": "The objectId of the user, group, or service principal for the role."
      }
    },
    "labName": {
      "type": "string",
      "metadata": {
        "description": "The name of the lab instance to be created."
      }
    },
    "roleAssignmentGuid": {
      "type": "string",
      "metadata": {
        "description": "Guid to use as the name for the role assignment."
      }
    }
  },
  "variables": {
    "devTestLabUserRoleId": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/111111111-0000-0000-11111111111111111')]",
    "fullDevTestLabUserRoleName": "[concat(parameters('labName'), '/Microsoft.Authorization/', parameters('roleAssignmentGuid'))]",
    "roleScope": "[concat('/subscriptions/', subscription().subscriptionId, '/resourceGroups/', resourceGroup().name, '/providers/Microsoft.DevTestLab/labs/', parameters('labName'))]"
  },
  "resources": [
    {
      "apiVersion": "2016-05-15",
      "type": "Microsoft.DevTestLab/labs",
      "name": "[parameters('labName')]",
      "location": "[resourceGroup().location]"
    },
    {
      "apiVersion": "2016-07-01",
      "type": "Microsoft.DevTestLab/labs/providers/roleAssignments",
      "name": "[variables('fullDevTestLabUserRoleName')]",
      "properties": {
        "roleDefinitionId": "[variables('devTestLabUserRoleId')]",
        "principalId": "[parameters('principalId')]",
        "scope": "[variables('roleScope')]"
      },
      "dependsOn": [
        "[resourceId('Microsoft.DevTestLab/labs', parameters('labName'))]"
      ]
    }
  ]
}

Se você estiver atribuindo a função no mesmo modelo que está criando o laboratório, lembre-se de adicionar uma dependência entre o recurso de atribuição de função e o laboratório. Para obter mais informações, confira o artigo Como definir as dependências nos modelos do Azure Resource Manager.

Informações de recurso de atribuição de função

O recurso de atribuição de função precisa especificar o tipo e o nome.

A primeira coisa a ser observada é que o tipo do recurso não é Microsoft.Authorization/roleAssignments, como seria para um grupo de recursos. Em vez disso, o tipo de recurso segue o padrão {provider-namespace}/{resource-type}/providers/roleAssignments. Nesse caso, o tipo de recurso será Microsoft.DevTestLab/labs/providers/roleAssignments.

O nome da atribuição de função em si precisa ser globalmente exclusivo. O nome da atribuição usa o padrão {labName}/Microsoft.Authorization/{newGuid}. O newGuid é um valor de parâmetro para o modelo. Ele garante que o nome da atribuição de função seja exclusivo. Como não há nenhuma função de modelo para a criação de GUIDs, você precisa gerar um GUID por conta própria usando qualquer ferramenta geradora de GUIDs.

No modelo, o nome da atribuição de função é definido pela variável fullDevTestLabUserRoleName. A linha exata do modelo é:

"fullDevTestLabUserRoleName": "[concat(parameters('labName'), '/Microsoft.Authorization/', parameters('roleAssignmentGuid'))]"

Propriedades do recurso de atribuição de função

Uma atribuição de função define três propriedades. Ela precisa de roleDefinitionId, principalId e scope.

Definição de função

A ID de definição de função é o identificador de cadeia de caracteres para a definição de função existente. A ID da função está no formato /subscriptions/{subscription-id}/providers/Microsoft.Authorization/roleDefinitions/{role-definition-id}.

A ID da assinatura é obtida usando a função de modelo subscription().subscriptionId.

Você precisa obter a definição de função para a função interna DevTest Labs User. Para obter o GUID da função Usuário do DevTest Labs, você pode usar a API REST de Atribuições de Função ou o cmdlet Get-AzRoleDefinition.

$dtlUserRoleDefId = (Get-AzRoleDefinition -Name "DevTest Labs User").Id

A ID da função está definida na seção de variáveis e é chamada de devTestLabUserRoleId. No modelo, a ID da função é definida como: 111111111-0000-0000-11111111111111111.

"devTestLabUserRoleId": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/111111111-0000-0000-11111111111111111')]",

ID da entidade de segurança

A ID da entidade de segurança é a ID de objeto do usuário, grupo ou entidade de serviço do Active Directory que você deseja adicionar, como um usuário de laboratório, ao laboratório propriamente dito. O modelo usa o ObjectId como um parâmetro.

Você pode obter o ObjectId usando os cmdlets do PowerShell Get-AzureRMADUser, Get-AzureRMADGroup ou Get-AzureRMADServicePrincipal. Esses cmdlets retornam uma ou várias listas de objetos do Active Directory que têm uma propriedade de ID, que é a ID de objeto de que você precisa. O exemplo a seguir mostra como obter a ID de objeto de um usuário específico em uma empresa.

$userObjectId = (Get-AzureRmADUser -UserPrincipalName 'email@company.com').Id

Você também pode usar os cmdlets do PowerShell do Microsoft Graph que incluem Get-MgUser, Get-MgGroup e Get-MgServicePrincipal.

Escopo

Escopo especifica o recurso ou grupo de recursos para o qual a atribuição de função deve ser aplicada. Para recursos, o escopo fica no formato: /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{provider-namespace}/{resource-type}/{resource-name}. O modelo usa a função subscription().subscriptionId para preencher a parte subscription-id e a função de modelo resourceGroup().name para preencher a parte resource-group-name. O uso dessas funções significa que o laboratório ao qual você está atribuindo uma função precisa existir na assinatura atual e no mesmo grupo de recursos no qual a implantação de modelo é feita. A última parte, resource-name, é o nome do laboratório. Esse valor é recebido por meio do parâmetro de modelo neste exemplo.

O escopo da função no modelo:

"roleScope": "[concat('/subscriptions/', subscription().subscriptionId, '/resourceGroups/', resourceGroup().name, '/providers/Microsoft.DevTestLab/labs/', parameters('labName'))]"

Implantação do modelo

Primeiro, crie um arquivo de parâmetro (por exemplo: azuredeploy.parameters.json) que passe valores para parâmetros no modelo do Resource Manager.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "principalId": {
      "value": "11111111-1111-1111-1111-111111111111"
    },
    "labName": {
      "value": "MyLab"
    },
    "roleAssignmentGuid": {
      "value": "22222222-2222-2222-2222-222222222222"
    }
  }
}

Em seguida, use o cmdlet New-AzureRmResourceGroupDeployment do PowerShell para implantar o modelo do Resource Manager. O comando de exemplo a seguir atribui uma pessoa, um grupo ou uma entidade de serviço à função de Usuário do DevTest Labs para um laboratório.

New-AzureRmResourceGroupDeployment -Name "MyLabResourceGroup-$(New-Guid)" -ResourceGroupName 'MyLabResourceGroup' -TemplateParameterFile .\azuredeploy.parameters.json -TemplateFile .\azuredeploy.json

Observação

O nome da implantação de grupo e o GUID de atribuição de função devem ser exclusivos. Se você tentar implantar uma atribuição de recurso usando um GUID não exclusivo, será exibido um erro RoleAssignmentUpdateNotPermitted.

Se você planeja usar o modelo várias vezes para adicionar vários objetos do Active Directory à função de Usuário do DevTest Labs para o laboratório, considere usar objetos dinâmicos no comando do PowerShell. O exemplo a seguir usa o cmdlet New-Guid para especificar o nome da implantação do grupo de recursos e o GUID de atribuição de função dinamicamente.

New-AzureRmResourceGroupDeployment -Name "MyLabResourceGroup-$(New-Guid)" -ResourceGroupName 'MyLabResourceGroup' -TemplateFile .\azuredeploy.json -roleAssignmentGuid "$(New-Guid)" -labName "MyLab" -principalId "11111111-1111-1111-1111-111111111111"

Usar PowerShell do Azure

Conforme discutido na introdução, você cria uma atribuição de função do Azure para adicionar um usuário à função de Usuário do DevTest Labs para o laboratório. No PowerShell, você faz isso usando o cmdlet New-AzureRMRoleAssignment. Esse cmdlet tem muitos parâmetros opcionais, oferecendo flexibilidade. Um entre ObjectId, SigninName e ServicePrincipalName pode ser especificado como o objeto que recebe permissões.

Aqui está um exemplo de comando do Azure PowerShell que adiciona um usuário à função de Usuário do DevTest Labs no laboratório especificado.

New-AzureRmRoleAssignment -UserPrincipalName <email@company.com> -RoleDefinitionName 'DevTest Labs User' -ResourceName '<Lab Name>' -ResourceGroupName '<Resource Group Name>' -ResourceType 'Microsoft.DevTestLab/labs'

A especificação do recurso ao qual as permissões estão sendo concedidas pode ser realizada por uma combinação de ResourceName, ResourceType e ResourceGroup ou pelo parâmetro scope. Qualquer que seja combinação de parâmetros usada, forneça informações suficientes ao cmdlet para identificar exclusivamente o objeto do Active Directory (usuário, grupo ou entidade de serviço), o escopo (grupo de recursos ou recurso) e a definição de função.

Usar a CLI do Azure

Na CLI do Azure, usuário de laboratório é adicionado a um laboratório usando o comando az role assignment create. Para obter mais informações sobre cmdlets da CLI do Azure, confira Adicionar ou remover atribuições de função do Azure usando a CLI do Azure.

O objeto para o qual o acesso está sendo concedido pode ser especificado pelos parâmetros objectId, signInName e spn. O laboratório cujo acesso está sendo concedido ao objeto pode ser identificado pela URL scope ou por uma combinação dos parâmetros resource-name, resource-type e resource-group.

O exemplo da CLI do Azure a seguir mostra como adicionar uma pessoa à função de Usuário do DevTest Labs para o laboratório especificado.

az role assignment create --roleName "DevTest Labs User" --signInName <email@company.com> -–resource-name "<Lab Name>" --resource-type "Microsoft.DevTestLab/labs" --resource-group "<Resource Group Name>" --role Contributor --scope /subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroupName>

Próximas etapas

Veja os artigos a seguir:

• Criar e gerenciar máquinas virtuais com DevTest Labs usando a CLI do Azure
• Criar uma máquina virtual com o DevTest Labs usando o Azure PowerShell
• Usar ferramentas de linha de comando para iniciar e parar máquinas virtuais do Azure DevTest Labs