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

Saiba como usar scripts de implantação em modelos do Azure Resource Manager (modelos ARM). Os scripts de implantação podem ser usados para executar etapas personalizadas que não podem ser feitas por modelos ARM. Por exemplo, criar 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 script de implantação, consulte Usar scripts de implantação em modelos ARM.

Este tutorial abrange as seguintes tarefas:

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

Pré-requisitos

Para concluir este artigo, precisa de:

• Código do Visual Studio.

• 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 Identidade gerenciada atribuída pelo usuário. Você precisa do ID de identidade ao implantar o modelo. O formato da identidade é:

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

  Use o seguinte script da CLI 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 dos Modelos de Início Rápido do Azure. Os Modelos de Início Rápido do Azure são um repositório para modelos ARM.

O modelo usado neste início rápido é chamado Criar um Cofre de Chaves do Azure e um segredo. O modelo cria um cofre de chaves e, em seguida, adiciona um segredo ao cofre de chaves.

1. No Visual Studio Code, selecione Ficheiro>Abrir Ficheiro.

2. Em 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 Arquivo>Salvar como para salvar o arquivo como azuredeploy.json no 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 dos parâmetros durante a implantação.

Configurar as políticas de acesso ao cofre de chaves

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

1. Adicione um parâmetro para obter o ID de identidade gerenciado:

   "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 ao 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 ao cofre de chaves existentes do Microsoft.KeyVault/vaults recurso 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 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 que são usados pelo script de implantação:

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

2. Adicionar 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 backtick (`).

   {
     "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 de cofre de chave e do recurso de atribuição de função. Tem as seguintes 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, apenas scripts do PowerShell são suportados.
   • forceUpdateTag: Determine se o script de implantação deve ser executado mesmo que a origem do script não tenha sido alterada. Pode ser um carimbo de data/hora atual ou um GUID. Para saber mais, consulte 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 suporta as versões 2.7.0, 2.8.0 e 3.0.0.
   • timeout: Especifique o tempo máximo permitido de execução do script especificado no formato ISO 8601. O valor padrão é P1D.
   • arguments: Especifique os valores dos parâmetros. 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. A $DeploymentScriptOutputs declaração só é necessária ao testar o script em uma máquina local. Declarar a variável permite que o script seja executado em uma máquina local e em um deploymentScript recurso sem ter que 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 do script de implantação. O valor padrão é Always, o que significa que os recursos do script de implantação são excluídos apesar do estado do terminal (Succeeded, Failed, Canceled). Neste tutorial, OnSuccess é usado para que você tenha a chance de visualizar 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. Esta propriedade é usada quando cleanupPreference é definida como OnExpiration. Esta propriedade não está habilitada atualmente.

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

   $DeploymentScriptOutputs é usado para armazenar o valor de saída. Para saber mais, consulte 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 completo 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 Arquivo>Salvar para salvar o arquivo.

Implementar o modelo

1. Entre no Azure Cloud Shell

2. Escolha seu ambiente preferido selecionando PowerShell ou Bash (para CLI) no canto superior esquerdo. Reiniciar o shell é necessário quando você alterna.

   

3. Selecione Carregar/transferir ficheiros e, em seguida, selecione Carregar. Veja a captura de tela anterior. Selecione o arquivo que você salvou 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 implementação precisa criar recursos de script de implementação adicionais para a execução de script. O processo de preparação e limpeza pode levar até um minuto para ser concluído, 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 do script de implantação para a finalidade de solução de problemas.

Depurar o script falhado

1. Inicie sessão no portal Azure.

2. Abra o grupo de recursos. É o nome do projeto com rg anexado. 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 do 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 em 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, porque a cleanupPreference propriedade está definida como OnSuccess.

Limpeza de 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. Selecione Excluir grupo de recursos no menu superior.

Próximos passos

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