Azure Uygulama Hizmeti ve Azure İşlevleri'nde uygulama ayarları olarak Key Vault referanslarını kullanma

2025-05-22

Bu makalede, Azure App Service veya Azure İşlevleri uygulamalarınızda uygulama ayarlarının veya bağlantı dizelerinin değerleri olarak Azure Key Vault'taki gizli dizilerin nasıl kullanılacağı gösterilmektedir.

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 Key Vault başvurusu olduğunda, uygulama kodunuz bunu diğer uygulama ayarları veya bağlantı dizeleri gibi kullanabilir. Böylece, gizli bilgileri uygulamanızın yapılandırmasından ayrı tutabilirsiniz. Uygulama ayarları bekleme sırasında güvenli bir şekilde şifrelenir, ancak gizli bilgileri yönetmek için özelliklere ihtiyacınız varsa, bir anahtar kasasına yerleştirilmelidir.

Uygulamanıza bir anahtar kasasına erişim izni verin

Anahtar kasasından gizli bilgileri okumak için önce bir anahtar kasası oluşturmanız ve uygulamanıza erişim izni vermeniz gerekir.

"Key Vault hızlı başlangıç kılavuzunu izleyerek bir anahtar kasası oluşturun."
Uygulamanız için yönetilen kimlik oluşturun.

Anahtar kasası referansları, varsayılan olarak uygulamanın sistem tarafından atanan kimliğini kullanır, ancak kullanıcı tarafından atanan bir kimlik belirtebilirsiniz.
Oluşturduğunuz yönetilen kimlik için, anahtar kasanızdaki gizli bilgilere okuma erişimi yetkisi verin. Bunu nasıl yapacağınız, 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. 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 Sırları Getir iznini atayın. Bakınız Key Vault erişim ilkesi atama.

Ağ erişimi kısıtlı kasalara erişim

Kasadaki yapılandırma ağ kısıtlamaları içeriyorsa, uygulamanın ağ erişimine sahip olduğundan emin olun. Gizli bilginin talep edildiği kaynak IP adresi farklı olabileceğinden kasalar uygulamanın genel çıkış IP adreslerine bağımlı olmamalıdır. Bunun yerine, kasa uygulamanın kullandığı bir sanal ağdan gelen trafiği kabul etmek üzere yapılandırılmalıdır.

App Service ağ özellikleri ve Azure İşlevleri ağ seçenekleri bölümünde açıklandığı gibi uygulamanın yapılandırılmış giden ağ özelliklerine sahip olduğundan emin olun.

Şu anda, özel uç noktalara bağlanan Linux uygulamalarının tüm trafiği sanal ağ üzerinden yönlendirecek şekilde açıkça yapılandırılması gerekir. Bu ayarı yapılandırmak için aşağıdaki komutu çalıştırın:
- Azure CLI
- Azure PowerShell
```
az webapp config set --resource-group <group-name>  --subscription <subscription> --name <app-name> --generic-configurations '{"vnetRouteAllEnabled": true}'
```
```
Update-AzFunctionAppSetting -Name <app-name> -ResourceGroupName <group-name> -AppSetting @{vnetRouteAllEnabled = $true}
```
Depo yapılandırmasının, uygulamanızın erişmek için kullandığı ağ veya alt ağa izin verdiğinden emin olun.

tr-TR: Kasa, sanal ağınızdan gelen trafiği kabul edecek şekilde doğru yapılandırılmış olsa bile, kasanın denetim günlükleri, uygulamanın genel giden IP'sinden başarısız bir (403 - Yasak) SecretGet olayını hala gösterebilir. Bu, uygulamanın özel IP'sinden gelen başarılı bir SecretGet olayı ile takip edilecek ve bu, tasarım gereğidir.

Kullanıcı tarafından atanmış kimlik ile kasalara erişim sağla.

Sistem tarafından atanan bir kimlik henüz kullanılabilir olmadığında bazı uygulamalar oluşturulurken gizli bilgilere başvurması gerekir. Böyle durumlarda, kullanıcı tarafından atanan bir kimlik oluşturun ve ona kasaya erişim izni önceden verin.

Kullanıcı tarafından atanan kimliğe izinler verdikten sonra şu adımları izleyin:

Kimliği uygulamanıza atayın.

Kullanıcı tarafından atanan kimliğin kaynak kimliğini keyVaultReferenceIdentity özelliğine ayarlayarak uygulamayı, Key Vault başvuru işlemleri için bu kimliği kullanacak şekilde yapılandırın.

Azure CLI
Azure PowerShell

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}

$identityResourceId = Get-AzUserAssignedIdentity -ResourceGroupName <group-name> -Name <identity-name> | Select-Object -ExpandProperty Id
$appResourceId = Get-AzFunctionApp -ResourceGroupName <group-name> -Name <app-name> | Select-Object -ExpandProperty Id

$Path = "{0}?api-version=2021-01-01" -f $appResourceId
Invoke-AzRestMethod -Method PATCH -Path $Path -Payload "{'properties':{'keyVaultReferenceIdentity':'$identityResourceId'}}"

Bu ayar, uygulama için tüm Key Vault başvuruları için geçerlidir.

Dönüşü anla

Gizli sürüm referansta belirtilmezse, uygulama anahtar kasasındaki mevcut en son sürümü kullanır. Döndürme 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 Key Vault başvurularının 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 sırların hemen yeniden alınmasına neden olur.

Uygulamanızın Key Vault başvurularının çözülmesini zorlamak için API uç noktasına https://management.azure.com/[Resource ID]/config/configreferences/appsettings/refresh?api-version=2022-03-01kimliği doğrulanmış bir POST isteği gönderin.

Key Vault'tan kaynak uygulama ayarlarını anlama

Key Vault başvurusu kullanmak için, başvuruyu yapılandırma değeri olarak belirleyin. Uygulamanız anahtarını kullanarak normal şekilde gize başvurabilir. Kod değişikliği gerekmez.

Tavsiye

Her ortam için ayrı kasalarınız olması gerektiğinden, Key Vault referanslarını kullanan uygulama ayarlarının çoğu slot ayarları olarak işaretlenmelidir.

Key Vault başvurusu, aşağıdaki biçimlerden birinde yer alan @Microsoft.KeyVault({referenceString}) biçimindedir{referenceString}:

Referans dizesi	Açıklama
`SecretUri=<secretUri>`	`SecretUri` kasadaki bir sırrın tam veri düzlemi URI'si olmalıdır. Örneğin, `https://myvault.vault.azure.net/secrets/mysecret`. İsteğe bağlı olarak, örneğin `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931` gibi bir sürüm ekleyin.
`VaultName=<vaultName>;SecretName=<secretName>`;`SecretVersion=<secretVersion>`	`VaultName` değeri gereklidir ve kasanın adıdır. `SecretName` Değer gereklidir ve gizli adıdır. `SecretVersion` Değer isteğe bağlıdır, ancak varsa kullanılacak gizli dizinin sürümünü gösterir.

Örneğin, belirli bir sürümü olmayan tam bir 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, WEBSITE_CONTENTAZUREFILECONNECTIONSTRING kullanarak dosya sistemi olarak Azure Dosyalar bağlayabilir. Bu ayar, uygulamanın düzgün şekilde başlatılabilmesini sağlamak için doğrulama denetimlerine sahiptir.

Platform, Azure Files üzerinde içerik paylaşımına sahip olmayı gerektiriyor. Platform, ayar WEBSITE_CONTENTSHARE kullanılarak belirtilmedikçe varsayılan bir ad kabul eder. Platform, bu ayarları değiştiren tüm istekler için bu içerik paylaşımının mevcut olduğunu doğrular. İçerik paylaşımı yoksa platform bunu oluşturmaya çalışır. Platform içerik paylaşımını bulamıyor veya oluşturamıyorsa isteği engeller.

Bu ayarda Key Vault başvurularını kullandığınızda, gelen isteğin işlenmesi sırasında gizli dizi çözümlenemediğinden doğrulama denetimi varsayılan olarak başarısız olur. Bu sorunu önlemek için doğrulamayı atlamak amacıyla WEBSITE_SKIP_CONTENTSHARE_VALIDATION ayarını 1 olarak ayarlayabilirsiniz. Bu ayar App Service'e tüm denetimleri atlamasını söyler ve içerik paylaşımını sizin için oluşturmaz. İçerik paylaşımının önceden oluşturulduğundan 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ılmaz ve HTTP 500 hataları oluşturur.

Uygulamayı oluşturmanın bir parçası olarak, içerik paylaşımını yükleme işlemi, yönetilen kimlik izinleri aktarılmadığından veya sanal ağ entegrasyonu ayarlanmadığından başarısız olabilir. Bu durumu dikkate almak için dağıtım şablonunda daha sonra Azure Dosyaları ayarlamayı erteleyebilirsiniz. Daha fazla bilgi için bu makalenin devamında yer alan Azure Resource Manager dağıtımına bakın.

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.

Application Insights araçları için dikkate alınması gereken hususlar

Uygulamalar, APPINSIGHTS_INSTRUMENTATIONKEY veya APPLICATIONINSIGHTS_CONNECTION_STRING uygulama ayarlarını kullanarak Application Insights ile tümleşebilir.

App Service ve Azure İşlevleri için, Azure portalı bu ayarları kaynaktan telemetri verilerini görüntülemek için de kullanır. Bu değerlere Key Vault'tan başvurulursa, bu yaklaşım kullanılamaz. Bunun yerine telemetriyi görüntülemek için doğrudan Application Insights kaynağıyla çalışmanız gerekir. Ancak bu değerler gizli olarak kabul edilmez; bu nedenle, Key Vault 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 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. 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]"
                    }
                }
            ]
        }
    ]
}

Uyarı

Bu örnekte, kaynak denetimi dağıtımı uygulama ayarlarına bağlıdır. Uygulama ayarı güncelleştirmesi zaman uyumsuz davrandığından bu bağımlılık normalde güvenli değildir. Ancak, WEBSITE_ENABLE_SYNC_UPDATE_SITE uygulama ayarını dahil ettiğiniz için güncelleştirme zaman uyumludur. Kaynak denetimi dağıtımı ancak uygulama ayarları tamamen güncelleştirildikten sonra başlar. Daha fazla uygulama ayarını görmek için Azure App Service'teki ortam değişkenlerine ve uygulama ayarlarına bakın.

Key Vault referanslarında sorun giderme

Bir başvuru düzgün çözümlenmezse, bunun yerine başvuru dizesi kullanılır, örneğin, @Microsoft.KeyVault(...). Bu durum, uygulamanın farklı bir değere sahip gizli bir şey beklediğinden hata vermesine neden olabilir.

Çözümlenememesi genellikle Key Vault erişim ilkesinin yanlış yapılandırılmasından kaynaklanır. Ancak, bunun nedeni bir sırın artık mevcut olmaması veya referansın söz dizimi hatası içermesi de olabilir.

Söz dizimi doğruysa, Azure portalında geçerli çözümleme durumunu denetleyerek hatanın diğer nedenlerini görüntüleyebilirsiniz. Uygulama Ayarları'na 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 Key Vault başvurusu olarak tanınmadığı anlamına gelir.

Daha fazla bilgi edinmek için yerleşik algılayıcılardan birini de kullanabilirsiniz.

App Service için algılayıcıyı kullanmak için:

Azure portalında uygulamanıza gidin.
Sorunları tanılama ve çözme’yi seçin.
Kullanılabilirlik ve Performans>Web uygulaması kapalı.
Arama kutusunda Key Vault Uygulama Ayarları Tanılama'yı arayın ve seçin.

Azure İşlevleri için algılayıcıyı kullanmak için:

Azure portalında uygulamanıza gidin.
Platform özellikleri'ne gidin.
Sorunları tanılama ve çözme’yi seçin.
Kullanılabilirlik ve Performans>Fonksiyon uygulaması çalışmıyor veya hatalar bildiriliyor'u seçin.
Key Vault Uygulama Ayarları Tanılama'yı seçin.