Tutorial: Usar scripts de implantação para criar um certificado autoassinado

Saiba como usar scripts de implantação em modelos do ARM (Azure Resource Manager). Os scripts de implantação podem ser usados para executar etapas personalizadas que não podem ser feitas por modelos do ARM. Por exemplo, criando um certificado autoassinado. Neste tutorial, você cria um modelo para implantar um cofre de chaves do Azure e, em seguida, usa um Microsoft.Resources/deploymentScripts recurso no mesmo modelo para criar um certificado e, em seguida, adicionar o certificado ao cofre de chaves. Para saber mais sobre o script de implantação, consulte Usar scripts de implantação em modelos do ARM.

Este tutorial aborda as seguintes tarefas:

Para obter um módulo do Learn que abrange scripts de implantação, consulte Estender modelos do ARM usando scripts de implantação.

Pré-requisitos

Para concluir este artigo, você precisa do seguinte:

• Visual Studio Code.

• Uma identidade gerenciada atribuída pelo usuário. Essa identidade é usada para executar ações específicas do Azure no script. Para criar uma, consulte a identidade gerenciada atribuída pelo usuário. Você precisa da ID de identidade ao implantar o modelo. O formato da identidade é:

  /subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<IdentityID>
  

  Use o script da CLI a seguir para obter a ID fornecendo o nome do grupo de recursos e o nome da identidade.

  • CLI
  • PowerShell

  echo "Enter the Resource Group name:" &&
  read resourceGroupName &&
  az identity list -g $resourceGroupName
  

Abrir um modelo de Início Rápido

Em vez de criar um modelo do zero, você abre um modelo de Modelos de Início Rápido do Azure. Os Modelos de Início Rápido do Azure são um repositório para modelos do ARM.

O modelo usado neste início rápido é chamado Criar um Azure Key Vault e um segredo. O modelo cria um cofre de chaves e adiciona um segredo ao cofre de chaves.

1. No Visual Studio Code, selecione Arquivo>Aberto arquivo.

2. No nome do arquivo, cole a seguinte URL:

   https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.keyvault/key-vault-create/azuredeploy.json
   

3. Selecione Abrir para abrir o arquivo.

4. Selecione Salvar Arquivo>como para salvar o arquivo como azuredeploy.json em seu computador local.

Editar o modelo

Faça as seguintes alterações no modelo:

Limpar o modelo (opcional)

O modelo original adiciona um segredo ao cofre de chaves. Para simplificar o tutorial, remova o seguinte recurso:

• Microsoft.KeyVault/vaults/secrets

Remova as duas definições de parâmetro a seguir:

• secretName
• secretValue

Se você optar por não remover essas definições, precisará especificar os valores de parâmetro durante a implantação.

Configurar as políticas de acesso do cofre de chaves

O script de implantação adiciona um certificado ao cofre de chaves. Configure as políticas de acesso do cofre de chaves para conceder permissão à identidade gerenciada:

1. Adicione um parâmetro para obter a ID de identidade gerenciada:

   "identityId": {
     "type": "string",
     "metadata": {
       "description": "Specifies the ID of the user-assigned managed identity."
     }
   },
   

2. Adicione um parâmetro para configurar as políticas de acesso do cofre de chaves para que a identidade gerenciada possa adicionar certificados ao cofre de chaves:

   "certificatesPermissions": {
     "type": "array",
     "defaultValue": [
       "get",
       "list",
       "update",
       "create"
     ],
     "metadata": {
     "description": "Specifies the permissions to certificates in the vault. Valid values are: all, get, list, update, create, import, delete, recover, backup, restore, manage contacts, manage certificate authorities, get certificate authorities, list certificate authorities, set certificate authorities, delete certificate authorities."
     }
   }
   

3. Atualize as políticas de acesso do cofre de chaves existentes do recurso Microsoft.KeyVault/vaults para:

   "accessPolicies": [
     {
       "objectId": "[parameters('objectId')]",
       "tenantId": "[parameters('tenantId')]",
       "permissions": {
         "keys": "[parameters('keysPermissions')]",
         "secrets": "[parameters('secretsPermissions')]",
         "certificates": "[parameters('certificatesPermissions')]"
       }
     },
     {
       "objectId": "[reference(parameters('identityId'), '2018-11-30').principalId]",
       "tenantId": "[parameters('tenantId')]",
       "permissions": {
         "keys": "[parameters('keysPermissions')]",
         "secrets": "[parameters('secretsPermissions')]",
         "certificates": "[parameters('certificatesPermissions')]"
       }
     }
   ],
   

   Há duas políticas definidas, uma para o usuário conectado e a outra é para a identidade gerenciada. O usuário conectado só precisa da permissão de lista para verificar a implantação. Para simplificar o tutorial, o mesmo certificado é atribuído à identidade gerenciada e aos usuários conectados.

Adicionar o script de implantação

1. Adicione três parâmetros usados pelo script de implantação:

   "certificateName": {
     "type": "string",
     "defaultValue": "DeploymentScripts2019"
   },
   "subjectName": {
     "type": "string",
     "defaultValue": "CN=contoso.com"
   },
   "utcValue": {
     "type": "string",
     "defaultValue": "[utcNow()]"
   }
   

2. Adicione um deploymentScripts recurso:

   Observação

   Como os scripts de implantação embutidos são colocados entre aspas duplas, as cadeias de caracteres dentro dos scripts de implantação precisam ser colocadas entre aspas simples. O caractere de escape do PowerShell é o acento grave (`).

   {
     "type": "Microsoft.Resources/deploymentScripts",
     "apiVersion": "2023-08-01",
     "name": "createAddCertificate",
     "location": "[resourceGroup().location]",
     "dependsOn": [
       "[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]"
     ],
     "identity": {
       "type": "UserAssigned",
       "userAssignedIdentities": {
         "[parameters('identityId')]": {
         }
       }
     },
     "kind": "AzurePowerShell",
     "properties": {
       "forceUpdateTag": "[parameters('utcValue')]",
       "azPowerShellVersion": "3.0",
       "timeout": "PT30M",
       "arguments": "[format(' -vaultName {0} -certificateName {1} -subjectName {2}', parameters('keyVaultName'), parameters('certificateName'), parameters('subjectName'))]", // can pass an argument string, double quotes must be escaped
       "scriptContent": "
         param(
           [string] [Parameter(Mandatory=$true)] $vaultName,
           [string] [Parameter(Mandatory=$true)] $certificateName,
           [string] [Parameter(Mandatory=$true)] $subjectName
         )
   
         $ErrorActionPreference = 'Stop'
         $DeploymentScriptOutputs = @{}
   
         $existingCert = Get-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName
   
         if ($existingCert -and $existingCert.Certificate.Subject -eq $subjectName) {
   
           Write-Host 'Certificate $certificateName in vault $vaultName is already present.'
   
           $DeploymentScriptOutputs['certThumbprint'] = $existingCert.Thumbprint
           $existingCert | Out-String
         }
         else {
           $policy = New-AzKeyVaultCertificatePolicy -SubjectName $subjectName -IssuerName Self -ValidityInMonths 12 -Verbose
   
           # private key is added as a secret that can be retrieved in the Resource Manager template
           Add-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName -CertificatePolicy $policy -Verbose
   
           # it takes a few seconds for KeyVault to finish
           $tries = 0
           do {
             Write-Host 'Waiting for certificate creation completion...'
             Start-Sleep -Seconds 10
             $operation = Get-AzKeyVaultCertificateOperation -VaultName $vaultName -Name $certificateName
             $tries++
   
             if ($operation.Status -eq 'failed')
             {
               throw 'Creating certificate $certificateName in vault $vaultName failed with error $($operation.ErrorMessage)'
             }
   
             if ($tries -gt 120)
             {
               throw 'Timed out waiting for creation of certificate $certificateName in vault $vaultName'
             }
           } while ($operation.Status -ne 'completed')
   
           $newCert = Get-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName
           $DeploymentScriptOutputs['certThumbprint'] = $newCert.Thumbprint
           $newCert | Out-String
         }
       ",
       "cleanupPreference": "OnSuccess",
       "retentionInterval": "P1D"
     }
   }
   

   O deploymentScripts recurso depende do recurso do cofre de chaves e do recurso de atribuição de função. Ele tem estas propriedades:

   • identity: o script de implantação usa uma identidade gerenciada atribuída pelo usuário para executar as operações no script.
   • kind: especifique o tipo de script. Atualmente, há suporte apenas para scripts do PowerShell.
   • forceUpdateTag: determine se o script de implantação deve ser executado mesmo que a origem do script não tenha sido alterada. Pode ser o carimbo de data/hora atual ou um GUID. Para saber mais, confira Executar script mais de uma vez.
   • azPowerShellVersion: especifica a versão do módulo do Azure PowerShell a ser usada. Atualmente, o script de implantação dá suporte à versão 2.7.0, 2.8.0 e 3.0.0.
   • timeout: especifique o tempo máximo de execução de script permitido especificado no formato ISO 8601. O valor padrão é P1D.
   • arguments: especifique os valores de parâmetro. Os valores são separados por espaços.
   • scriptContent: especifique o conteúdo do script. Para executar um script externo, use primaryScriptURI em vez disso. Para obter mais informações, consulte Usar script externo. É necessário declarar $DeploymentScriptOutputs apenas ao testar o script em um computador local. Declarar a variável permite que o script seja executado em um computador local e em um deploymentScript recurso sem precisar fazer alterações. O valor atribuído a $DeploymentScriptOutputs está disponível como saídas nas implantações. Para obter mais informações, consulte Trabalhar com saídas de scripts de implantação do PowerShell ou Trabalhar com saídas de scripts de implantação da CLI.
   • cleanupPreference: especifique a preferência sobre quando excluir os recursos de script de implantação. O valor padrão é Always, o que significa que os recursos de script de implantação são excluídos apesar do estado do terminal (Bem-sucedido, com falha, cancelado). Neste tutorial, o OnSuccess é usado para que você tenha a chance de exibir os resultados da execução do script.
   • retentionInterval: especifique o intervalo para o qual o serviço retém os recursos de script depois de atingir um estado terminal. Os recursos serão excluídos quando essa duração expirar. A duração é baseada no padrão ISO 8601. Este tutorial usa P1D, o que significa um dia. Essa propriedade é usada quando cleanupPreference é definida como OnExpiration. Essa propriedade não está habilitada no momento.

   O script de implantação usa três parâmetros: keyVaultName, certificateNamee subjectName. Ele cria um certificado e adiciona o certificado ao cofre de chaves.

   $DeploymentScriptOutputs é usado para armazenar o valor de saída. Para saber mais, confira Trabalhar com saídas de scripts de implantação do PowerShell ou Trabalhar com saídas de scripts de implantação da CLI.

   O modelo concluído pode ser encontrado aqui.

3. Para ver o processo de depuração, coloque um erro no código adicionando a seguinte linha ao script de implantação:

   Write-Output1 $keyVaultName
   

   O comando correto é Write-Output em vez de Write-Output1.

4. Selecione Salvar Arquivo> para salvar o arquivo.

Implantar o modelo

1. Faça login no Azure Cloud Shell

2. Escolha seu ambiente preferido selecionando o PowerShell ou o Bash (para CLI) no canto superior esquerdo. A reinicialização do shell é necessária quando você alterna.

   

3. Selecione Carregar/baixar arquivos e, em seguida, selecione Carregar. Confira a captura de tela anterior. Selecione o arquivo salvo na seção anterior. Depois de carregar o arquivo, você pode usar o ls comando e o cat comando para verificar se o arquivo foi carregado com êxito.

4. Execute o seguinte script da CLI do Azure ou do Azure PowerShell para implantar o modelo.

   • CLI
   • PowerShell

   echo "Enter a project name that is used to generate resource names:" &&
   read projectName &&
   echo "Enter the location (i.e. centralus):" &&
   read location &&
   echo "Enter your email address used to sign in to Azure:" &&
   read upn &&
   echo "Enter the user-assigned managed identity ID:" &&
   read identityId &&
   adUserId=$((az ad user show --id ${upn}) | jq -r '.id') &&
   resourceGroupName="${projectName}rg" &&
   keyVaultName="${projectName}kv" &&
   az group create --name $resourceGroupName --location $location &&
   az deployment group create --resource-group $resourceGroupName --template-file "$HOME/azuredeploy.json" --parameters identityId=$identityId keyVaultName=$keyVaultName objectId=$adUserId
   

   O serviço de script de implantação precisa criar recursos adicionais de script de implantação para sua execução. A preparação e o processo de limpeza podem levar até um minuto para serem concluídos, além do tempo real de execução do script.

   A implantação falhou porque o comando Write-Output1 inválido é usado no script. Você receberá um erro dizendo:

   The term 'Write-Output1' is not recognized as the name of a cmdlet, function, script file, or operable
   program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
   

   O resultado da execução do script de implantação é armazenado nos recursos de script de implantação para a finalidade de solução de problemas.

Depurar o script que falhou

1. Entre no portal do Azure.

2. Abra o grupo de recursos. É o nome do projeto com rg acrescentado. Você verá dois recursos adicionais no grupo de recursos. Esses recursos são chamados de recursos de script de implantação.

   

   Ambos os arquivos têm o sufixo azscripts . Uma é uma conta de armazenamento e a outra é uma instância de contêiner.

   Selecione Mostrar tipos ocultos para listar o deploymentScripts recurso.

3. Selecione a conta de armazenamento com o sufixo azscripts .

4. Selecione o bloco Compartilhamentos de arquivos. Você verá uma pasta azscripts que contém os arquivos de execução de script de implantação.

5. Selecione azscripts. Você verá duas pastas azscriptinput e azscriptoutput. A pasta de entrada contém um arquivo de script do PowerShell do sistema e os arquivos de script de implantação do usuário. A pasta de saída contém um executionresult.json e o arquivo de saída de script. Você pode ver a mensagem de erro no executionresult.json. O arquivo de saída não está lá porque a execução falhou.

Remova a Write-Output1 linha e reimplante o modelo.

Quando a segunda implantação for executada com êxito, os recursos de script de implantação serão removidos pelo serviço de script, pois a cleanupPreference propriedade está definida como OnSuccess.

Limpar os recursos

Quando os recursos do Azure não forem mais necessários, limpe os recursos implantados excluindo o grupo de recursos.

1. No portal do Azure, selecione Grupo de recursos no menu à esquerda.
2. Insira o nome do grupo de recursos no campo Filtrar por nome .
3. Selecione o nome do grupo de recursos.
4. Escolha Excluir grupo de recursos no menu superior.

Próximas etapas

Neste tutorial, você aprendeu a usar um script de implantação em modelos do ARM. Para saber como implantar recursos do Azure com base em condições, confira: