Samouczek: tworzenie certyfikatu z podpisem własnym przy użyciu skryptów wdrażania

Artykuł
03/20/2024

Dowiedz się, jak używać skryptów wdrażania w szablonach usługi Azure Resource Manager (szablony usługi ARM). Skrypty wdrażania mogą służyć do wykonywania niestandardowych kroków, których nie można wykonać za pomocą szablonów usługi ARM. Na przykład utworzenie certyfikatu z podpisem własnym. W tym samouczku utworzysz szablon do wdrożenia usługi Azure Key Vault, a następnie użyjesz Microsoft.Resources/deploymentScripts zasobu w tym samym szablonie, aby utworzyć certyfikat, a następnie dodać certyfikat do magazynu kluczy. Aby dowiedzieć się więcej na temat skryptu wdrażania, zobacz Używanie skryptów wdrażania w szablonach usługi ARM.

Ważne

Dwa zasoby skryptu wdrażania, konto magazynu i wystąpienie kontenera, są tworzone w tej samej grupie zasobów na potrzeby wykonywania skryptu i rozwiązywania problemów. Te zasoby są zwykle usuwane przez usługę skryptów, gdy wykonanie skryptu jest w stanie terminalu. Opłaty są naliczane za zasoby do momentu usunięcia zasobów. Aby dowiedzieć się więcej, zobacz Oczyszczanie zasobów skryptu wdrażania.

Ten samouczek obejmuje następujące zadania:

Otwieranie szablonu szybkiego startu
Edytowanie szablonu
Wdrażanie szablonu
Debugowanie skryptu, który zakończył się niepowodzeniem
Czyszczenie zasobów

Aby zapoznać się z modułem Learn obejmującym skrypty wdrażania, zobacz Rozszerzanie szablonów usługi ARM przy użyciu skryptów wdrażania.

Wymagania wstępne

Aby ukończyć pracę z tym artykułem, potrzebne są następujące zasoby:

Program Visual Studio Code z rozszerzeniem Narzędzia usługi Resource Manager. Zobacz Szybki start: tworzenie szablonów usługi ARM przy użyciu programu Visual Studio Code.
Tożsamość zarządzana przypisana przez użytkownika. Ta tożsamość służy do wykonywania akcji specyficznych dla platformy Azure w skrycie. Aby je utworzyć, zobacz Tożsamość zarządzana przypisana przez użytkownika. Identyfikator tożsamości jest potrzebny podczas wdrażania szablonu. Format tożsamości to:
```
/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<IdentityID>
```
Użyj następującego skryptu interfejsu wiersza polecenia, aby uzyskać identyfikator, podając nazwę grupy zasobów i nazwę tożsamości.
- Interfejs wiersza polecenia
- Program PowerShell
```
echo "Enter the Resource Group name:" &&
read resourceGroupName &&
az identity list -g $resourceGroupName
```
```
$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
(Get-AzUserAssignedIdentity -ResourceGroupName $resourceGroupname).id

Write-Host "Press [ENTER] to continue ..."
```

Otwieranie szablonu szybkiego startu

Zamiast tworzyć szablon od podstaw, otwórz szablon z obszaru Azure Quickstart Templates (Szablony szybkiego startu platformy Azure). Szablony szybkiego startu platformy Azure to repozytorium szablonów usługi ARM.

Szablon używany w tym przewodniku Szybki start jest nazywany tworzeniem usługi Azure Key Vault i wpisem tajnym. Szablon tworzy magazyn kluczy, a następnie dodaje wpis tajny do magazynu kluczy.

W programie Visual Studio Code wybierz pozycję File (Plik)>Open File (Otwórz plik).

W polu File name (Nazwa pliku) wklej następujący adres URL:

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

Wybierz pozycję Open (Otwórz), aby otworzyć plik.
Wybierz pozycję File (Plik)>Save As (Zapisz jako), aby zapisać plik jako azuredeploy.json na komputerze lokalnym.

Edytowanie szablonu

Wprowadź następujące zmiany w szablonie:

Czyszczenie szablonu (opcjonalnie)

Oryginalny szablon dodaje wpis tajny do magazynu kluczy. Aby uprościć samouczek, usuń następujący zasób:

Microsoft.KeyVault/vaults/secrets

Usuń następujące dwie definicje parametrów:

secretName
secretValue

Jeśli nie chcesz usuwać tych definicji, musisz określić wartości parametrów podczas wdrażania.

Konfigurowanie zasad dostępu do magazynu kluczy

Skrypt wdrażania dodaje certyfikat do magazynu kluczy. Skonfiguruj zasady dostępu do magazynu kluczy, aby przyznać uprawnienia tożsamości zarządzanej:

Dodaj parametr , aby uzyskać identyfikator tożsamości zarządzanej:
```
"identityId": {
  "type": "string",
  "metadata": {
    "description": "Specifies the ID of the user-assigned managed identity."
  }
},
```
Uwaga

Rozszerzenie szablonu usługi Resource Manager programu Visual Studio Code nie może jeszcze sformatować skryptów wdrażania. Nie używaj klawiszy Shift+Alt+F do formatowania deploymentScripts zasobów, takich jak poniższe.

Dodaj parametr do konfigurowania zasad dostępu magazynu kluczy, aby tożsamość zarządzana mogła dodawać certyfikaty do magazynu kluczy:

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

Zaktualizuj istniejące zasady dostępu do magazynu kluczy, aby:

"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')]"
    }
  }
],

Zdefiniowano dwie zasady, jedną dla zalogowanego użytkownika, a drugą dla tożsamości zarządzanej. Zalogowany użytkownik potrzebuje tylko uprawnień do listy , aby zweryfikować wdrożenie. Aby uprościć samouczek, ten sam certyfikat jest przypisywany zarówno do tożsamości zarządzanej, jak i zalogowanych użytkowników.

Dodawanie skryptu wdrażania

Dodaj trzy parametry, które są używane przez skrypt wdrażania:

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

deploymentScripts Dodaj zasób:

Uwaga

Ponieważ skrypty wdrażania wbudowanego są ujęte w cudzysłowy, zamiast tego ciągi wewnątrz skryptów wdrażania muszą być ujęte w pojedynczy cudzysłów. Znak ucieczki programu PowerShell to backtick (`).
```
{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-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"
  }
}
```
Zasób deploymentScripts zależy od zasobu magazynu kluczy i zasobu przypisania roli. Ma następujące właściwości:
- identity: Skrypt wdrażania używa tożsamości zarządzanej przypisanej przez użytkownika do wykonywania operacji w skry skrycie.
- kind: określ typ skryptu. Obecnie obsługiwane są tylko skrypty programu PowerShell.
- forceUpdateTag: określ, czy skrypt wdrożenia powinien zostać wykonany, nawet jeśli źródło skryptu nie zostało zmienione. Może być bieżącą sygnaturą czasową lub identyfikatorem GUID. Aby dowiedzieć się więcej, zobacz Uruchamianie skryptu więcej niż raz.
- azPowerShellVersion: określa wersję modułu programu Azure PowerShell, która ma być używana. Obecnie skrypt wdrażania obsługuje wersję 2.7.0, 2.8.0 i 3.0.0.
- timeout: określ maksymalny dozwolony czas wykonywania skryptu określony w formacie ISO 8601. Wartość domyślna to P1D.
- arguments: Określ wartości parametrów. Wartości są oddzielone spacjami.
- scriptContent: określ zawartość skryptu. Aby uruchomić skrypt zewnętrzny, zamiast tego użyj polecenia primaryScriptURI . Aby uzyskać więcej informacji, zobacz Używanie skryptu zewnętrznego. Deklarowanie $DeploymentScriptOutputs jest wymagane tylko podczas testowania skryptu na komputerze lokalnym. Deklarowanie zmiennej umożliwia uruchamianie skryptu na komputerze lokalnym i w zasobie deploymentScript bez konieczności wprowadzania zmian. Wartość przypisana do $DeploymentScriptOutputs elementu jest dostępna jako dane wyjściowe we wdrożeniach. Aby uzyskać więcej informacji, zobacz Work with outputs from PowerShell deployment scripts (Praca ze skryptami wdrażania programu PowerShell) lub Work with outputs from CLI deployment scripts (Praca ze skryptami wdrażania interfejsu wiersza polecenia).
- cleanupPreference: określ preferencje dotyczące usuwania zasobów skryptu wdrożenia. Wartość domyślna to Zawsze, co oznacza, że zasoby skryptu wdrożenia są usuwane pomimo stanu terminalu (Powodzenie, Niepowodzenie, Anulowanie). W tym samouczku użyto polecenia OnSuccess, aby móc wyświetlić wyniki wykonywania skryptu.
- retentionInterval: określ interwał, dla którego usługa zachowuje zasoby skryptu po osiągnięciu stanu terminalu. Zasoby zostaną usunięte po wygaśnięciu tego czasu trwania. Czas trwania jest oparty na wzorcu ISO 8601. W tym samouczku jest używana funkcja P1D, co oznacza jeden dzień. Ta właściwość jest używana, gdy cleanupPreference jest ustawiona na Wartość OnExpiration. Ta właściwość nie jest obecnie włączona.
Skrypt wdrażania przyjmuje trzy parametry: keyVaultName, certificateNamei subjectName. Tworzy certyfikat, a następnie dodaje certyfikat do magazynu kluczy.

$DeploymentScriptOutputs służy do przechowywania wartości wyjściowej. Aby dowiedzieć się więcej, zobacz Praca z danymi wyjściowymi ze skryptów wdrażania programu PowerShell lub Praca z danymi wyjściowymi ze skryptów wdrażania interfejsu wiersza polecenia.

Ukończony szablon można znaleźć tutaj.
Aby wyświetlić proces debugowania, umieść błąd w kodzie, dodając następujący wiersz do skryptu wdrażania:
```
Write-Output1 $keyVaultName
```
Poprawne polecenie to Write-Output zamiast Write-Output1.
Wybierz pozycję File (Plik)>Save (Zapisz), aby zapisać plik.

Wdrażanie szablonu

Zaloguj się do usługi Azure Cloud Shell
Wybierz preferowane środowisko, wybierając pozycję PowerShell lub Bash (dla interfejsu wiersza polecenia) w lewym górnym rogu. Po przełączeniu wymagane jest ponowne uruchomienie powłoki.
Wybierz pozycję Przekaż/pobierz pliki, a następnie wybierz pozycję Przekaż. Zobacz poprzedni zrzut ekranu. Wybierz plik, który został zapisany w poprzedniej sekcji. Po przekazaniu pliku możesz użyć ls polecenia i cat polecenia , aby sprawdzić, czy plik został pomyślnie przekazany.

Uruchom następujący skrypt interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell, aby wdrożyć szablon.

Interfejs wiersza polecenia
Program 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

$projectName = Read-Host -Prompt "Enter a project name that is used to generate resource names"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"
$upn = Read-Host -Prompt "Enter your email address used to sign in to Azure"
$identityId = Read-Host -Prompt "Enter the user-assigned managed identity ID"

$adUserId = (Get-AzADUser -UserPrincipalName $upn).Id
$resourceGroupName = "${projectName}rg"
$keyVaultName = "${projectName}kv"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateFile "$HOME/azuredeploy.json" -identityId $identityId -keyVaultName $keyVaultName -objectId $adUserId

Write-Host "Press [ENTER] to continue ..."

Usługa skryptu wdrożenia musi utworzyć dodatkowe zasoby skryptu wdrożenia na potrzeby wykonywania skryptu. Przygotowanie i proces oczyszczania może potrwać do jednej minuty, oprócz rzeczywistego czasu wykonywania skryptu.

Wdrożenie nie powiodło się, Write-Output1 ponieważ nieprawidłowe polecenie jest używane w skrycie. Zostanie wyświetlony komunikat o błędzie z informacją:

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.

Wynik wykonywania skryptu wdrożenia jest przechowywany w zasobach skryptu wdrażania na potrzeby rozwiązywania problemów.

Debugowanie skryptu, który zakończył się niepowodzeniem

Zaloguj się w witrynie Azure Portal.
Otwórz grupę zasobów. Jest to nazwa projektu z dołączonym elementem rg . W grupie zasobów zostaną wyświetlone dwa dodatkowe zasoby. Te zasoby są określane jako zasoby skryptu wdrażania.

Oba pliki mają sufiks azscripts . Jedno to konto magazynu, a drugie to wystąpienie kontenera.

Wybierz pozycję Pokaż ukryte typy , aby wyświetlić listę deploymentScripts zasobów.
Wybierz konto magazynu z sufiksem azscripts .
Wybierz kafelek Udziały plików. Zostanie wyświetlony folder azscripts zawierający pliki wykonywania skryptu wdrażania.
Wybierz pozycję azscripts. Zostaną wyświetlone dwa foldery azscriptinput i azscriptoutput. Folder input zawiera systemowy plik skryptu programu PowerShell i pliki skryptów wdrożenia użytkownika. Folder wyjściowy zawiera plik output executionresult.json i plik wyjściowy skryptu. W pliku executionresult.json jest wyświetlany komunikat o błędzie. Plik wyjściowy nie istnieje, ponieważ wykonanie nie powiodło się.

Write-Output1 Usuń wiersz i ponownie wdróż szablon.

Po pomyślnym uruchomieniu drugiego wdrożenia zasoby skryptu wdrożenia zostaną usunięte przez usługę skryptu, ponieważ cleanupPreference właściwość jest ustawiona na Wartość OnSuccess.

Czyszczenie zasobów

Gdy zasoby platformy Azure nie będą już potrzebne, wyczyść wdrożone zasoby, usuwając grupę zasobów.

W witrynie Azure Portal wybierz pozycję Grupa zasobów z menu po lewej stronie.
Wprowadź nazwę grupy zasobów w polu Filtruj według nazwy.
Wybierz nazwę grupy zasobów.
Wybierz pozycję Usuń grupę zasobów z górnego menu.

Następne kroki

W tym samouczku przedstawiono sposób używania skryptu wdrażania w szablonach usługi ARM. Aby dowiedzieć się, jak wdrażać zasoby platformy Azure na podstawie warunków, zobacz:

Warunki użytkowania