Tutorial: Menggunakan skrip penerapan untuk membuat sertifikat yang ditandatangani sendiri

  • Artikel

Mempelajari cara menggunakan skrip penerapan di templat Azure Resource Manager (templat ARM). Skrip penerapan dapat digunakan untuk melakukan langkah-langkah kustom yang tidak dapat dilakukan oleh templat ARM. Misalnya, membuat sertifikat yang ditandatangani sendiri. Dalam tutorial ini, Anda membuat templat untuk menggunakan brankas kunci Azure, lalu menggunakan Microsoft.Resources/deploymentScripts sumber daya dalam templat yang sama untuk membuat sertifikat lalu menambahkan sertifikat ke brankas kunci. Untuk mempelajari selengkapnya tentang skrip penerapan, lihat Menggunakan skrip penerapan di templat ARM.

Penting

Dua sumber daya skrip penerapan, satu akun penyimpanan, dan satu instans kontainer, dibuat dalam grup sumber daya yang sama untuk eksekusi dan pemecahan masalah skrip. Sumber daya ini biasanya dihapus oleh layanan skrip ketika eksekusi skrip masuk ke status terminal. Anda ditagih untuk sumber daya hingga sumber daya dihapus. Untuk mempelajari lebih lanjut, lihat Membersihkan sumber daya skrip penerapan.

Tutorial ini mencakup tugas-tugas berikut:

  • Membuka templat mulai cepat
  • Mengedit templat
  • Menyebarkan templat
  • Melakukan debug skrip gagal
  • Membersihkan sumber daya

Untuk modul Microsoft Learn yang mencakup skrip penyebaran, lihat Memperluas template ARM dengan menggunakan skrip penyebaran.

Prasyarat

Untuk menyelesaikan artikel ini, Anda perlu:

  • Visual Studio Code dengan ekstensi Alat Resource Manager. Lihat Mulai Cepat: Membuat templat ARM dengan Visual Studio Code.

  • Identitas yang dikelola yang ditetapkan pengguna. Identitas ini digunakan untuk melakukan tindakan khusus Azure di skrip. Untuk membuat identitas, lihat Identitas yang dikelola yang ditetapkan pengguna. Anda memerlukan ID identitas saat Anda menerapkan templat. Format identitasnya adalah:

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

    Gunakan skrip CLI berikut untuk mendapatkan ID dengan memberikan nama grup sumber daya dan nama identitas.

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

Membuka templat Mulai Cepat

Alih-alih membuat templat dari awal, Anda membuka templat dari Templat Mulai Cepat Azure. Templat Mulai Cepat Azure adalah repositori untuk templat ARM.

Templat yang digunakan dalam mulai cepat ini disebut Membuat Azure Key Vault dan rahasia. Templat membuat brankas kunci, lalu menambahkan rahasia ke brankas kunci.

  1. Dari Visual Studio Code, pilih File>Buka File.

  2. Di Nama file, tempelkan URL berikut:

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

  3. Pilih Buka untuk membuka file.

  4. Pilih File>Simpan Sebagai untuk menyimpan file sebagai azuredeploy.json ke komputer lokal Anda.

Mengedit templat

Lakukan perubahan berikut ini pada templat:

Bersihkan templat (opsional)

Templat asli menambahkan rahasia ke brankas kunci. Untuk menyederhanakan tutorial, hapus sumber daya berikut:

  • Microsoft.KeyVault/vaults/secrets

Hapus dua definisi parameter berikut:

  • secretName
  • secretValue

Jika Anda memilih untuk tidak menghapus definisi ini, Anda perlu menentukan nilai parameter selama penerapan.

Mengonfigurasikan kebijakan akses brankas kunci

Skrip penerapan menambahkan sertifikat ke brankas kunci. Mengonfigurasikan kebijakan akses brankas kunci untuk memberikan izin ke identitas yang dikelola:

  1. Tambahkan parameter untuk mendapatkan ID identitas yang dikelola:

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

    Catatan

    Ekstensi templat Resource Manager dari Visual Studio Code belum mampu memformat skrip penerapan. Jangan gunakan Shift+Alt+F untuk memformat deploymentScripts sumber daya, seperti yang berikut ini.

  2. Tambahkan parameter untuk mengonfigurasi kebijakan akses brankas kunci sehingga identitas yang dikelola dapat menambahkan sertifikat ke brankas kunci:

    "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. Perbarui kebijakan akses brankas kunci yang ada ke:

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

    Ada dua kebijakan yang ditentukan, satu untuk pengguna yang masuk, dan yang lainnya adalah untuk identitas yang dikelola. Pengguna yang masuk hanya memerlukan izin daftar untuk memverifikasi penerapan. Untuk menyederhanakan tutorial, sertifikat yang sama ditetapkan untuk identitas yang dikelola dan pengguna yang masuk.

Tambahkan skrip penerapan

  1. Tambahkan tiga parameter yang digunakan oleh skrip penerapan:

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

  2. Tambahkan deploymentScripts sumber daya:

    Catatan

    Karena skrip penerapan sebaris diapit dalam tanda kutip ganda, string di dalam skrip penerapan perlu dimasukkan dalam tanda kutip tunggal sebagai gantinya. Escape character PowerShell adalah 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"
  }
}

    Sumber daya deploymentScripts tergantung pada sumber daya brankas kunci dan sumber daya penetapan peran. Sumber daya ini memiliki properti-properti berikut:

    • identity: Skrip penerapan menggunakan identitas yang dikelola yang ditetapkan pengguna untuk operasi dalam skrip.
    • kind: Menentukan jenis skrip. Saat ini, hanya skrip PowerShell yang didukung.
    • forceUpdateTag: Menentukan apakah skrip penerapan harus dijalankan meskipun sumber skrip belum berubah. Bisa stempel waktu saat ini atau GUID. Untuk mempelajari lebih lanjut, lihat Menjalankan skrip lebih dari sekali.
    • azPowerShellVersion: Menentukan versi modul Azure PowerShell yang akan digunakan. Saat ini, skrip penerapan mendukung versi 2.7.0, 2.8.0, dan 3.0.0.
    • timeout: Menentukan waktu eksekusi skrip maksimum yang diizinkan yang ditentukan dalam format ISO 8601. Nilai default adalah P1D.
    • arguments: Menentukan nilai parameter. Nilai dipisahkan oleh spasi.
    • scriptContent: Menentukan konten skrip. Untuk menjalankan skrip eksternal, gunakan primaryScriptURI sebagai gantinya. Untuk informasi selengkapnya, lihat Menggunakan skrip eksternal. Menyatakan $DeploymentScriptOutputs hanya diperlukan ketika menguji skrip pada komputer lokal. Menyatakan variabel memungkinkan skrip dijalankan di komputer lokal dan sumber deploymentScript daya tanpa harus membuat perubahan. Nilai yang ditetapkan $DeploymentScriptOutputs tersedia sebagai output dalam penerapan. Untuk informasi selengkapnya, lihat Bekerja dengan output dari skrip penerapan PowerShell atau Bekerja dengan output dari skrip penerapan CLI.
    • cleanupPreference: Menentukan preferensi kapan harus menghapus sumber daya skrip penerapan. Nilai default adalah Selalu,yang berarti sumber daya skrip penerapan dihapus meskipun ada status terminal (Berhasil, Gagal, Dibatalkan). Dalam tutorial ini, OnSuccess digunakan agar Anda mendapat kesempatan melihat hasil eksekusi skrip.
    • retentionInterval: Menentukan interval di mana layanan mempertahankan sumber daya skrip setelah mencapai status terminal. Sumber daya akan dihapus ketika durasi ini berakhir. Durasi didasarkan pada pola ISO 8601. Tutorial ini menggunakan P1D, yang berarti satu hari. Properti ini digunakan ketika cleanupPreference diatur ke OnExpiration. Properti ini saat ini tidak diaktifkan.

    Skrip penerapan mengambil tiga parameter: keyVaultName, certificateName, dan subjectName. Properti ini membuat sertifikat, lalu menambahkan sertifikat ke brankas kunci.

    $DeploymentScriptOutputs digunakan untuk menyimpan nilai output. Untuk informasi selengkapnya, lihat Bekerja dengan output dari skrip penerapan PowerShell atau Bekerja dengan output dari skrip penerapan CLI.

    Templat yang selesai dapat ditemukan di sini.

  3. Untuk melihat proses penelusuran kesalahan, letakkan kesalahan dalam kode dengan menambahkan baris berikut ke skrip penerapan:

    Write-Output1 $keyVaultName

    Perintah yang benar adalah Write-Output bukan Write-Output1.

  4. Pilih File>Simpan untuk menyimpan file.

Menyebarkan templat

  1. Masuk ke Azure Cloud Shell

  2. Pilih lingkungan pilihan Anda dengan memilih PowerShell atau Bash (untuk CLI) di sudut kiri atas. Menghidupkan ulang shell diperlukan saat Anda beralih.

    Azure portal Cloud Shell upload file

  3. Pilih Unggah/unduh file, lalu pilih Unggah. Lihat cuplikan layar sebelumnya. Pilih file yang Anda simpan di bagian sebelumnya. Setelah mengunggah file, Anda dapat menggunakan perintah ls dan perintah cat untuk memverifikasi file berhasil diunggah.

  4. Jalankan skrip Azure CLI atau Azure PowerShell berikut untuk menyebarkan templat.

    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

    Layanan skrip penerapan perlu membuat sumber daya skrip penerapan tambahan untuk eksekusi skrip. Persiapan dan proses pembersihan dapat memakan waktu hingga satu menit untuk diselesaikan selain waktu eksekusi skrip aktual.

    Penerapan gagal karena perintah tidak valid, Write-Output1 digunakan dalam skrip. Anda akan mendapatkan kesalahan yang mengatakan:

    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.

    Hasil eksekusi skrip penerapan disimpan dalam sumber daya skrip penerapan untuk tujuan pemecahan masalah.

Melakukan debug skrip gagal

  1. Masuk ke portal Azure.

  2. Buka grup sumber daya. Ini adalah nama proyek dengan tambahan rg. Anda akan melihat dua sumber daya tambahan dalam grup sumber daya. Sumber daya ini disebut sebagai sumber daya skrip penerapan.

    Resource Manager template deployment script resources

    Kedua file memiliki akhiran azscripts. Salah satunya adalah akun penyimpanan dan yang lainnya adalah instans kontainer.

    Pilih Perlihatkan jenis tersembunyi untuk mendaftarkan deploymentScripts sumber daya.

  3. Pilih akun penyimpanan dengan akhiran azscript.

  4. Pilih petak berbagi File. Anda akan melihat folder azscript yang berisi file eksekusi skrip penerapan.

  5. Pilih azscripts. Anda akan melihat dua folder azscriptinput dan azscriptoutput. Folder input berisi file skrip PowerShell sistem dan file skrip penerapan pengguna. Folder output berisi executionresult.json dan file output skrip. Anda dapat melihat pesan kesalahan di executionresult.jsdi. Output keluaran tidak ada karena eksekusi gagal.

Menghapus Write-Output1 baris dan menerapkan kembali templat.

Ketika penerapan kedua berjalan dengan sukses, sumber daya skrip penerapan akan dihapus oleh layanan skrip, karena cleanupPreference properti diatur ke OnSuccess.

Membersihkan sumber daya

Saat sumber daya Azure tidak lagi diperlukan, bersihkan sumber daya yang Anda sebarkan dengan menghapus grup sumber daya.

  1. Dari portal Azure, pilih Grup sumber daya dari menu sebelah kiri.
  2. Masukkan nama grup sumber daya di bidang Filter menurut nama.
  3. Pilih nama grup sumber daya.
  4. Pilih Hapus grup sumber daya dari menu atas.

Langkah berikutnya

Dalam tutorial ini, Anda belajar cara menggunakan skrip penerapan dalam templat ARM. Untuk belajar cara menggunakan sumber daya Azure berdasarkan kondisi, lihat:

Menggunakan kondisi