Key Vault başvurularını Azure Uygulaması Hizmeti ve Azure İşlevleri uygulama ayarları olarak kullanma
Not
1 Haziran 2024'te, yeni oluşturulan tüm App Service uygulamalarının adlandırma kuralıyla <app-name>-<random-hash>benzersiz bir varsayılan ana bilgisayar adı oluşturma seçeneği olacaktır.<region>..azurewebsites.net Mevcut uygulamaların adları değişmez.
Örnek: myapp-ds27dh7271aah175.westus-01.azurewebsites.net
Daha fazla bilgi için bkz. App Service Kaynağı için Benzersiz Varsayılan Ana Bilgisayar Adı.
Bu makalede, App Service veya Azure İşlevleri uygulamalarınızda uygulama ayarları veya bağlantı dizesi değerleri olarak Azure Key Vault'taki gizli dizilerin nasıl kullanılacağı gösterilmektedir.
Azure Key Vault , erişim ilkeleri ve denetim geçmişi üzerinde tam denetime sahip merkezi gizli dizi yönetimi sağlayan bir hizmettir. Uygulama ayarı veya bağlantı dizesi bir anahtar kasası başvurusu olduğunda, uygulama kodunuz bunu diğer uygulama ayarları veya bağlantı dizesi gibi kullanabilir. Bu şekilde, gizli dizileri uygulamanızın yapılandırmasından ayrı tutabilirsiniz. Uygulama ayarları bekleme sırasında güvenli bir şekilde şifrelenir, ancak gizli dizi yönetimi özelliklerine ihtiyacınız varsa bir anahtar kasasına girmeleri gerekir.
Uygulamanıza bir anahtar kasasına erişim verme
Bir anahtar kasasından gizli dizileri okumak için bir kasa oluşturmanız ve uygulamanıza erişim izni vermeniz gerekir.
Key Vault hızlı başlangıcını izleyerek bir anahtar kasası oluşturun.
Uygulamanız için yönetilen kimlik oluşturun.
Anahtar kasası başvuruları varsayılan olarak uygulamanın sistem tarafından atanan kimliğini kullanır, ancak kullanıcı tarafından atanan bir kimlik belirtebilirsiniz.
Daha önce oluşturduğunuz yönetilen kimlik için anahtar kasanızdaki gizli dizilere okuma erişimi yetkisi verin. Bunu nasıl yapabileceğiniz, anahtar kasanızın izin modeline bağlıdır:
- Azure rol tabanlı erişim denetimi: Yönetilen kimliğe Key Vault Gizli Dizileri Kullanıcı rolünü atayın. Yönergeler için bkz . Azure rol tabanlı erişim denetimiyle Key Vault anahtarlarına, sertifikalarına ve gizli dizilerine erişim sağlama.
- Kasa erişim ilkesi: Yönetilen kimliğe Gizli dizi alma iznini atayın. Yönergeler için bkz . Key Vault erişim ilkesi atama.
Ağ ile kısıtlanmış kasalara erişme
Kasanız ağ kısıtlamalarıyla yapılandırılmışsa uygulamanın ağ erişimine sahip olduğundan emin olun. Gizli dizi isteğinin kaynak IP'si farklı olabileceğinden kasalar uygulamanın genel giden IP'lerine bağımlı olmamalıdır. Bunun yerine, kasanın uygulama tarafından kullanılan bir sanal ağdan gelen trafiği kabul etmek üzere yapılandırılması gerekir.
App Service ağ özellikleri ve Azure İşlevleri ağ seçeneklerinde açıklandığı gibi uygulamanın yapılandırılmış giden ağ özelliklerine sahip olduğundan emin olun.
Özel uç noktalara bağlanan Linux uygulamaları, tüm trafiği sanal ağ üzerinden yönlendirecek şekilde açıkça yapılandırılmalıdır. Bu gereksinim, gelecek bir güncelleştirmede kaldırılacaktır. Bu ayarı yapılandırmak için aşağıdaki komutu çalıştırın:
az webapp config set --subscription <sub> -g <group-name> -n <app-name> --generic-configurations '{"vnetRouteAllEnabled": true}'Kasa yapılandırmasının uygulamanızın erişmek için kullandığı ağa veya alt ağa izin verdiğinden emin olun.
Kullanıcı tarafından atanan kimliğe sahip kasalara erişme
Sistem tarafından atanan bir kimlik henüz kullanılabilir olmadığında bazı uygulamaların oluşturma zamanında gizli dizilere başvurması gerekir. Böyle durumlarda, kullanıcı tarafından atanan bir kimlik oluşturulabilir ve kasaya önceden erişim verilebilir.
Kullanıcı tarafından atanan kimliğe izin verdikten sonra şu adımları izleyin:
Henüz yapmadıysanız kimliği uygulamanıza atayın.
özelliğini kullanıcı tarafından atanan kimliğin kaynak kimliğine ayarlayarak
keyVaultReferenceIdentityuygulamayı anahtar kasası başvuru işlemleri için bu kimliği kullanacak şekilde yapılandırın.identityResourceId=$(az identity show --resource-group <group-name> --name <identity-name> --query id -o tsv) az webapp update --resource-group <group-name> --name <app-name> --set keyVaultReferenceIdentity=${identityResourceId}
Bu ayar, uygulama için tüm anahtar kasası başvuruları için geçerlidir.
Döndürme
Gizli dizi sürümü başvuruda belirtilmezse, uygulama anahtar kasasında bulunan en son sürümü kullanır. Döndürme olayı gibi daha yeni sürümler kullanıma sunulduğunda uygulama otomatik olarak güncelleştirilir ve 24 saat içinde en son sürümü kullanmaya başlar. Gecikmenin nedeni, App Service’in anahtar kasası başvuru değerlerini önbelleğe alıp 24 saatte bir yeniden oluşturmasıdır. Uygulamada yapılan herhangi bir yapılandırma değişikliği, uygulamanın yeniden başlatılmasına ve başvurulan tüm gizli dizilerin hemen yeniden başlatılmasına neden olur.
Anahtar kasasından kaynak uygulama ayarları
Anahtar kasası başvurusu kullanmak için, başvuruyu ayarın değeri olarak ayarlayın. Uygulamanız anahtarıyla normal şekilde gizli diziye başvurabilir. Kod değişikliği gerekmez.
İpucu
Her ortam için ayrı kasalarınız olması gerektiği için, anahtar kasası başvurularını kullanan uygulama ayarlarının çoğu yuva ayarları olarak işaretlenmelidir.
Anahtar kasası başvurusu, aşağıdaki biçimlerden birinde yer alan {referenceString} biçimindedir@Microsoft.KeyVault({referenceString}):
| Başvuru dizesi | Açıklama |
|---|---|
| SecretUri=secretUri | SecretUri, isteğe bağlı olarak bir sürüm de dahil olmak üzere kasadaki bir gizli dizinin tam veri düzlemi URI'si olmalıdır; örneğin, https://myvault.vault.azure.net/secrets/mysecret/ veyahttps://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931 |
| VaultName=vaultName; SecretName=secretName; SecretVersion=secretVersion | VaultName gereklidir ve kasa adıdır. SecretName gereklidir ve gizli dizi adıdır. SecretVersion isteğe bağlıdır, ancak varsa kullanılacak gizli dizinin sürümünü gösterir. |
Örneğin, tam başvuru aşağıdaki dizeye benzer olacaktır:
@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)
Alternatif olarak:
@Microsoft.KeyVault(VaultName=myvault;SecretName=mysecret)
Azure Dosyalar bağlama ile ilgili dikkat edilmesi gerekenler
Uygulamalar, dosya sistemi olarak Azure Dosyalar bağlamak için uygulama ayarını kullanabilirWEBSITE_CONTENTAZUREFILECONNECTIONSTRING. Bu ayar, uygulamanın düzgün şekilde başlatılabilmesini sağlamak için doğrulama denetimlerine sahiptir. Platform, Azure Dosyalar içinde bir içerik paylaşımına sahip olmayı kullanır ve ayar aracılığıyla WEBSITE_CONTENTSHARE belirtilmemişse varsayılan bir ad kabul eder. Bu ayarları değiştiren tüm istekler için platform, bu içerik paylaşımının mevcut olup olmadığını doğrular ve yoksa oluşturmayı dener. İçerik paylaşımını bulamıyor veya oluşturamıyorsa isteği engeller.
Bu ayarda anahtar kasası başvurularını kullandığınızda, gelen istek işlenirken gizli dizi çözümlenemediğinden doğrulama denetimi varsayılan olarak başarısız olur. Bu sorunu önlemek için "1" ayarını yaparak WEBSITE_SKIP_CONTENTSHARE_VALIDATION doğrulamayı atlayabilirsiniz. Bu ayar App Service'e tüm denetimleri atlamasını söyler ve içerik paylaşımını sizin için oluşturmaz. Önceden oluşturulduğuna emin olmalısınız.
Dikkat
Doğrulamayı atlarsanız ve bağlantı dizesi veya içerik paylaşımı geçersizse, uygulama düzgün başlatılamaz ve yalnızca HTTP 500 hatalarına hizmet eder.
Uygulamayı oluşturmanın bir parçası olarak, yönetilen kimlik izinlerinin yayılmaması veya sanal ağ tümleştirmesinin ayarlanmaması nedeniyle içerik paylaşımını bağlama girişimi başarısız olabilir. Azure Dosyalar ayarlamayı dağıtım şablonunda daha sonra buna uyum sağlamak için erteleyebilirsiniz. Daha fazla bilgi edinmek için bkz . Azure Resource Manager dağıtımı . Bu durumda App Service, Azure Dosyalar ayarlanana ve dosyalar kopyalanmayana kadar varsayılan bir dosya sistemi kullanır. Azure Dosyalar bağlanmadan önce ara dönemde dağıtım girişimi olmadığından emin olmanız gerekir.
Uygulama Analizler izlemesi ile ilgili dikkat edilmesi gerekenler
Uygulamalar, Uygulama Analizler ile tümleştirmek için veya APPLICATIONINSIGHTS_CONNECTION_STRING uygulama ayarlarını kullanabilirAPPINSIGHTS_INSTRUMENTATIONKEY. Portal, App Service deneyimini yaşar ve Azure İşlevleri bu ayarları kaynaktan telemetri verilerini görüntülemek için de kullanır. Bu değerlere Key Vault'tan başvuruldıysa, bu deneyimler kullanılamaz ve bunun yerine telemetriyi görüntülemek için doğrudan Uygulama Analizler kaynağıyla çalışmanız gerekir. Ancak, bu değerler gizli dizi olarak kabul edilmez, bu nedenle alternatif olarak anahtar kasası başvurularını kullanmak yerine bunları doğrudan yapılandırmayı düşünebilirsiniz.
Azure Resource Manager dağıtımı
Azure Resource Manager şablonları aracılığıyla kaynak dağıtımlarını otomatikleştirdiğinizde, bu özelliğin çalışması için bağımlılıklarınızı belirli bir sırada sıralamanız gerekebilir. Uygulama tanımında bir siteConfig özellik kullanmak yerine uygulama ayarlarınızı kendi kaynakları olarak tanımladığınızdan emin olun. Bunun nedeni, sistem tarafından atanan kimliğin onunla oluşturulması ve erişim ilkesinde kullanılabilmesi için önce uygulamanın tanımlanması gerekir.
Aşağıdaki sahte şablon, bir işlev uygulamasının nasıl görünebileceğini gösteren bir örnektir:
{
//...
"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('storageConnectionStringName')).secretUriWithVersion, ')')]",
"WEBSITE_CONTENTAZUREFILECONNECTIONSTRING": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringName')).secretUriWithVersion, ')')]",
"APPINSIGHTS_INSTRUMENTATIONKEY": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('appInsightsKeyName')).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]"
}
}
]
}
]
}
Not
Bu örnekte, kaynak denetimi dağıtımı uygulama ayarlarına bağlıdır. Uygulama ayarı güncelleştirmesi zaman uyumsuz davrandıkça bu normalde güvenli olmayan bir davranıştır. Ancak, uygulama ayarını eklediğimiz için WEBSITE_ENABLE_SYNC_UPDATE_SITE güncelleştirme zaman uyumludur. Bu, kaynak denetimi dağıtımının yalnızca uygulama ayarları tamamen güncelleştirildikten sonra başlayacağı anlamına gelir. Daha fazla uygulama ayarı için bkz. Azure Uygulaması Service'te ortam değişkenleri ve uygulama ayarları.
Anahtar kasası başvurularında sorun giderme
Bir başvuru düzgün çözümlenmezse, bunun yerine başvuru dizesi kullanılır (örneğin, @Microsoft.KeyVault(...)). Farklı bir değerin gizli dizisini beklediğinden uygulamanın hata oluşturmasına neden olabilir.
Çözümlenememesi genellikle Key Vault erişim ilkesinin yanlış yapılandırılmasından kaynaklanır. Ancak, bunun nedeni artık var olmayan bir gizli dizi veya başvurunun kendisinde söz dizimi hatası da olabilir.
Söz dizimi doğruysa, portalda geçerli çözümleme durumunu denetleyerek hatanın diğer nedenlerini görüntüleyebilirsiniz. Uygulama Ayarlar'ne gidin ve söz konusu başvuru için "Düzenle"yi seçin. Düzenle iletişim kutusu, hatalar da dahil olmak üzere durum bilgilerini gösterir. Durum iletisini görmüyorsanız söz diziminin geçersiz olduğu ve anahtar kasası başvurusu olarak tanınmadığı anlamına gelir.
Ek bilgi almak için yerleşik algılayıcılardan birini de kullanabilirsiniz.
App Service için algılayıcıyı kullanma
- Portalda uygulamanıza gidin.
- Sorunları tanılama ve çözme’yi seçin.
- Kullanılabilirlik ve Performans'ı ve ardından Web uygulaması'nı seçin.
- Arama kutusunda Key Vault Uygulaması Ayarlar Tanılama'yı arayın ve seçin.
Azure İşlevleri için algılayıcıyı kullanma
- Portalda uygulamanıza gidin.
- Platform özellikleri'ne gidin.
- Sorunları tanılama ve çözme’yi seçin.
- Kullanılabilirlik ve Performans'ı seçin ve İşlev uygulaması'nı kapatın veya hataları bildirin.
- Key Vault Uygulaması Ayarlar Tanılama'yı seçin.