Menggunakan referensi Key Vault untuk App Service dan Azure Functions

  • Artikel
  • 7 menit untuk membaca

Topik ini memperlihatkan cara bekerja dengan rahasia dari Azure Key Vault di aplikasi App Service atau Azure Functions Anda tanpa memerlukan perubahan kode apa pun. Azure Key Vault adalah layanan yang menyediakan manajemen rahasia terpusat, dengan kontrol penuh atas kebijakan akses dan riwayat audit.

Memberikan akses aplikasi Anda ke Key Vault

Untuk membaca rahasia dari Key Vault, Anda harus membuat vault dan memberi izin aplikasi Anda untuk mengaksesnya.

  1. Buat key vault dengan mengikuti mulai cepat Vault Kunci.

  2. Buat identitas terkelola untuk aplikasi Anda.

    Referensi Key Vault akan menggunakan identitas yang ditetapkan oleh sistem secara default, tetapi Anda dapat menentukan identitas yang ditetapkan oleh pengguna.

  3. Buat kebijakan akses di Key Vault untuk identitas aplikasi yang Anda buat sebelumnya. Aktifkan izin rahasia "Get" pada kebijakan ini. Jangan konfigurasi "aplikasi resmi" atau pengaturan applicationId, karena tidak kompatibel dengan identitas terkelola.

Mengakses vault yang dibatasi jaringan

Jika vault Anda dikonfigurasi dengan batasan jaringan, Anda juga perlu memastikan aplikasi memiliki akses jaringan.

  1. Pastikan aplikasi mengonfigurasi kemampuan jaringan keluar, seperti yang dijelaskan dalam fitur jaringan App Service dan opsi jaringan Azure Functions.

    Aplikasi Linux yang mencoba menggunakan titik akhir privat juga mengharuskan aplikasi dikonfigurasi secara eksplisit untuk memiliki semua rute lalu lintas melalui jaringan virtual. Persyaratan ini akan dihapus dalam pembaruan yang akan datang. Untuk mengatur ini, gunakan perintah Azure CLI atau Azure PowerShell berikut:

    az webapp config set --subscription <sub> -g MyResourceGroupName -n MyAppName --generic-configurations '{"vnetRouteAllEnabled": true}'

  2. Pastikan konfigurasi vault mempertimbangkan jaringan atau subnet tempat aplikasi Anda mengaksesnya.

Catatan

Kontainer Windows saat ini tidak mendukung referensi Azure Key Vault melalui Integrasi VNet.

Mengakses brankas dengan identitas yang ditetapkan pengguna

Beberapa aplikasi perlu merujuk rahasia pada saat pembuatan, ketika identitas yang ditetapkan sistem belum tersedia. Dalam kasus ini, identitas yang ditetapkan pengguna dapat dibuat dan diberikan akses ke brankas terlebih dahulu.

Setelah Anda memberikan izin ke identitas yang ditetapkan oleh pengguna, ikuti langkah-langkah berikut:

  1. Tetapkan identitas ke aplikasi Anda, jika Anda belum melakukannya.

  2. Konfigurasikan aplikasi untuk menggunakan identitas ini untuk operasi referensi Key Vault dengan mengatur properti keyVaultReferenceIdentity ke ID sumber daya identitas yang ditetapkan oleh pengguna.

    userAssignedIdentityResourceId=$(az identity show -g MyResourceGroupName -n MyUserAssignedIdentityName --query id -o tsv)
appResourceId=$(az webapp show -g MyResourceGroupName -n MyAppName --query id -o tsv)
az rest --method PATCH --uri "${appResourceId}?api-version=2021-01-01" --body "{'properties':{'keyVaultReferenceIdentity':'${userAssignedIdentityResourceId}'}}"

Konfigurasi ini akan berlaku untuk semua referensi untuk aplikasi.

Sintaks referensi

Referensi Key Vault berbentuk @Microsoft.KeyVault({referenceString}), dengan {referenceString} digantikan oleh salah satu opsi berikut:

String referensi Deskripsi
SecretUri=secretUri SecretUri harus menjadi URI sarana data lengkap dari rahasia di Key Vault, secara opsional termasuk versi, misalnya, https://myvault.vault.azure.net/secrets/mysecret/ atauhttps://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931
VaultName=vaultName;SecretName=secretName;SecretVersion=secretVersion VaultName diperlukan dan harus menjadi nama sumber daya key Vault Anda. SecretName diperlukan dan harus menjadi nama rahasia target. SecretVersion bersifat opsional, tetapi jika ada menunjukkan versi rahasia yang akan digunakan.

Misalnya, referensi lengkap akan terlihat seperti berikut ini:

@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)

Atau:

@Microsoft.KeyVault(VaultName=myvault;SecretName=mysecret)

Rotasi

Jika versi tidak ditentukan dalam referensi, maka aplikasi akan menggunakan versi terbaru yang ada di brankas kunci. Saat versi yang lebih baru tersedia, seperti dengan peristiwa rotasi, aplikasi akan secara otomatis memperbarui dan mulai menggunakan versi terbaru dalam waktu 24 jam. Penundaan ini disebabkan karena App Service menyimpan nilai referensi brankas kunci dan mengambilnya kembali setiap 24 jam. Setiap perubahan konfigurasi pada aplikasi akan menyebabkan pengambilan kembali semua rahasia yang direferensikan.

Pengaturan Aplikasi Sumber dari Key Vault

Referensi Key Vault dapat digunakan sebagai nilai untuk Pengaturan Aplikasi, memungkinkan Anda menyimpan rahasia di Key Vault alih-alih di konfigurasi situs. Pengaturan Aplikasi dienkripsi dengan aman saat tidak aktif, tetapi jika Anda memerlukan kemampuan manajemen rahasia, mereka harus masuk ke Key Vault.

Agar dapat menggunakan referensi Key Vault untuk pengaturan aplikasi, set referensi sebagai nilai pengaturan. Aplikasi Anda dapat mereferensikan rahasia melalui kuncinya seperti biasa. Tidak ada perubahan kode yang diperlukan.

Tip

Sebagian besar pengaturan aplikasi yang menggunakan referensi Key Vault harus ditandai sebagai pengaturan slot, karena Anda harus memiliki vault terpisah untuk setiap lingkungan.

Pertimbangan untuk pemasangan Azure Files

Aplikasi dapat menggunakan pengaturan aplikasi WEBSITE_CONTENTAZUREFILECONNECTIONSTRING untuk memasang Azure Files sebagai sistem file. Pengaturan ini memiliki pemeriksaan validasi tambahan untuk memastikan aplikasi dapat dimulai dengan benar. Platform ini mengandalkan berbagi konten dalam Azure Files, dan menerima nama default kecuali satu yang ditentukan melalui pengaturan WEBSITE_CONTENTSHARE. Untuk permintaan apa pun yang mengubah pengaturan ini, platform akan berusaha untuk memvalidasi apakah berbagi konten ini ada, dan platform akan mencoba untuk membuatnya jika tidak ada. Jika platform tidak dapat menemukan atau membuat berbagi konten, permintaan diblokir.

Ketika menggunakan referensi Key Vault untuk pengaturan ini, pemeriksaan validasi ini akan gagal secara default, karena rahasia itu sendiri tidak dapat diselesaikan saat memproses permintaan masuk. Untuk menghindari masalah ini, Anda dapat melompati validasi dengan mengatur WEBSITE_SKIP_CONTENTSHARE_VALIDATION ke "1". Tindakan ini akan melewati semua pemeriksaan, dan berbagi konten tidak akan dibuat untuk Anda. Anda harus memastikan berbagi konten dibuat terlebih dahulu.

Perhatian

Jika Anda melompati validasi dan string koneksi atau berbagi konten tidak valid, aplikasi tidak akan dapat memulai dengan benar dan hanya akan menampilkan kesalahan HTTP 500.

Sebagai bagian dari pembuatan situs, ada kemungkinan juga bahwa upaya pemasangan berbagi konten dapat gagal karena izin identitas terkelola tidak disebarkan atau integrasi jaringan virtual tidak diatur. Anda dapat menunda pengaturan Azure Files hingga nanti di templat penyebaran untuk mengakomodasi ini. Lihat Penyebaran Azure Resource Manager untuk mempelajari selengkapnya. App Service akan menggunakan sistem file default hingga Azure Files disiapkan, dan file tidak disalin, jadi, Anda harus memastikan tidak ada upaya penyebaran yang terjadi selama periode sementara sebelum Azure Files dipasang.

Penyebaran Azure Resource Manager

Saat mengotomatiskan penyebaran sumber daya melalui templat Azure Resource Manager, Anda mungkin perlu mengurutkan dependensi Anda dalam urutan tertentu agar fitur ini berfungsi. Sebagai catatan, Anda harus mendefinisikan pengaturan aplikasi Anda sebagai sumber daya mereka sendiri, daripada menggunakan properti siteConfig dalam definisi situs. Ini karena situs perlu didefinisikan terlebih dahulu sehingga identitas yang ditetapkan sistem dibuat dengannya dan dapat digunakan dalam kebijakan akses.

Contoh templat semu untuk aplikasi fungsi mungkin terlihat seperti berikut ini:

{
    //...
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "name": "[variables('storageAccountName')]",
            //...
        },
        {
            "type": "Microsoft.Insights/components",
            "name": "[variables('appInsightsName')]",
            //...
        },
        {
            "type": "Microsoft.Web/sites",
            "name": "[variables('functionAppName')]",
            "identity": {
                "type": "SystemAssigned"
            },
            //...
            "resources": [
                {
                    "type": "config",
                    "name": "appsettings",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/secrets', variables('keyVaultName'), variables('storageConnectionStringName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/secrets', variables('keyVaultName'), variables('appInsightsKeyName'))]"
                    ],
                    "properties": {
                        "AzureWebJobsStorage": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringResourceId')).secretUriWithVersion, ')')]",
                        "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringResourceId')).secretUriWithVersion, ')')]",
                        "APPINSIGHTS_INSTRUMENTATIONKEY": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('appInsightsKeyResourceId')).secretUriWithVersion, ')')]",
                        "WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
                        //...
                    }
                },
                {
                    "type": "sourcecontrols",
                    "name": "web",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
                    ],
                }
            ]
        },
        {
            "type": "Microsoft.KeyVault/vaults",
            "name": "[variables('keyVaultName')]",
            //...
            "dependsOn": [
                "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
            ],
            "properties": {
                //...
                "accessPolicies": [
                    {
                        "tenantId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.tenantId]",
                        "objectId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.principalId]",
                        "permissions": {
                            "secrets": [ "get" ]
                        }
                    }
                ]
            },
            "resources": [
                {
                    "type": "secrets",
                    "name": "[variables('storageConnectionStringName')]",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
                    ],
                    "properties": {
                        "value": "[concat('DefaultEndpointsProtocol=https;AccountName=', variables('storageAccountName'), ';AccountKey=', listKeys(variables('storageAccountResourceId'),'2019-09-01').key1)]"
                    }
                },
                {
                    "type": "secrets",
                    "name": "[variables('appInsightsKeyName')]",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.Insights/components', variables('appInsightsName'))]"
                    ],
                    "properties": {
                        "value": "[reference(resourceId('microsoft.insights/components/', variables('appInsightsName')), '2019-09-01').InstrumentationKey]"
                    }
                }
            ]
        }
    ]
}

Catatan

Dalam contoh ini, penyebaran kontrol sumber bergantung pada pengaturan aplikasi. Perilaku ini biasanya tidak aman, karena pembaruan pengaturan aplikasi berperilaku asinkron. Namun, karena kita sudah menyertakan pengaturan aplikasi WEBSITE_ENABLE_SYNC_UPDATE_SITE, pembaruannya sinkron. Artinya penyebaran kontrol sumber hanya akan dimulai setelah pengaturan aplikasi sudah diperbarui sepenuhnya. Untuk pengaturan aplikasi lainnya, lihat Variabel lingkungan dan pengaturan aplikasi di Azure App Service.

Memecahkan Masalah Referensi Key Vault

Jika referensi tidak diselesaikan dengan benar, nilai referensi akan digunakan sebagai gantinya. Artinya untuk pengaturan aplikasi, variabel lingkungan akan dibuat yang nilainya memiliki sintaks @Microsoft.KeyVault(...). Ini dapat menyebabkan aplikasi menampilkan kesalahan, karena mengharapkan rahasia struktur tertentu.

Paling umum, ini disebabkan oleh kesalahan konfigurasi kebijakan akses Key Vault. Namun, ini juga bisa disebabkan oleh rahasia yang tidak lagi tersedia atau kesalahan sintaks dalam referensi itu sendiri.

Jika sintaks benar, Anda dapat melihat penyebab kesalahan lainnya dengan memeriksa status resolusi saat ini di portal. Buka Pengaturan Aplikasi dan pilih "Edit" untuk referensi yang dimaksud. Di bawah konfigurasi pengaturan, Anda akan melihat informasi status, termasuk kesalahan apa pun. Jika informasi status tidak ada, artinya sintaks referensi tidak valid.

Anda juga dapat menggunakan salah satu detektor bawaan untuk mendapatkan informasi tambahan.

Menggunakan detektor untuk App Service

  1. Di portal, navigasi ke aplikasi Anda.
  2. Pilih Diagnosis dan selesaikan masalah.
  3. Pilih Ketersediaan dan Performa dan pilih Aplikasi web tidak aktif.
  4. Temukan Diagnostik Pengaturan Aplikasi Key Vault dan klik Info selengkapnya.

Menggunakan detektor untuk Azure Functions

  1. Di portal, navigasi ke aplikasi Anda.
  2. Navigasi ke fitur Platform.
  3. Pilih Diagnosis dan selesaikan masalah.
  4. Pilih Ketersediaan dan Perfoma dan pilih Aplikasi fungsi tidak aktif atau melaporkan kesalahan.
  5. Klik Diagnostik Pengaturan Aplikasi Key Vault.