Azure App Service ve Azure İşlevleri'da uygulama ayarları olarak Key Vault başvuruları kullanma

  • Makale

Bu makalede, App Service veya Azure İşlevleri uygulamalarınızda uygulama ayarlarının veya bağlantı dizelerinin değerleri olarak Azure Key Vault gizli dizilerinin 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ı dizeleri 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 anahtar kasası erişimi verme

Bir anahtar kasasından gizli dizileri okumak için bir kasa oluşturmanız ve uygulamanıza erişim izni vermeniz gerekir.

  1. Key Vault hızlı başlangıcı izleyerek bir anahtar kasası oluşturun.

  2. 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.

  3. 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:

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 kasa, uygulama tarafından kullanılan bir sanal ağdan gelen trafiği kabul etmek üzere yapılandırılmalıdır.

  1. 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}'

  2. Kasa yapılandırmasının, uygulamanızın kullandığı ağın veya alt ağın bu ağa erişmesine izin verdiğinden emin olun.

Kullanıcı tarafından atanan kimliğe sahip kasalara erişme

Bazı uygulamaların, sistem tarafından atanan bir kimliğin henüz kullanılabilir olmadığı 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:

  1. Henüz yapmadıysanız, kimliği uygulamanıza atayın.

  2. özelliğini kullanıcı tarafından atanan kimliğin kaynak kimliğine ayarlayarak keyVaultReferenceIdentity uygulamayı 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, uygulamanın 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 tüm yapılandırma değişiklikleri, 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 normalde olduğu gibi anahtarı aracılığıyla gizli diziye başvurabilir. Kod değişikliği gerekmez.

İpucu

Her ortam için ayrı kasalarınız olması gerektiğinden, anahtar kasası başvurularını kullanan çoğu uygulama ayarı yuva ayarları olarak işaretlenmelidir.

Anahtar kasası başvurusu biçimindedir @Microsoft.KeyVault({referenceString}){referenceString} ve burada aşağıdaki biçimlerden birindedir:

Başvuru dizesi Description
SecretUri=secretUri SecretUri, kasadaki bir gizli dizinin tam veri düzlemi URI'si olmalıdır; isteğe bağlı olarak bir sürüm de dahil olmak üzere, örneğin veya https://myvault.vault.azure.net/secrets/mysecret/https://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, Azure Dosyalar dosya sistemi olarak bağlamak için uygulama ayarını kullanabilirWEBSITE_CONTENTAZUREFILECONNECTIONSTRING. Bu ayar, uygulamanın düzgün bir ş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 belirtilmediği sürece 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" olarak ayarlayarak WEBSITE_SKIP_CONTENTSHARE_VALIDATION doğrulamayı atlayabilirsiniz. Bu ayar, App Service tüm denetimleri atlamayı bildirir 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. Buna uyum sağlamak için dağıtım şablonunda Azure Dosyalar ayarlamayı daha sonraya 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 önceki ara dönemde dağıtım girişimi olmadığından emin olmanız gerekir.

Application Insights izlemesi için dikkat edilmesi gerekenler

Uygulamalar, Application Insights ile tümleştirmek için veya APPLICATIONINSIGHTS_CONNECTION_STRING uygulama ayarlarını kullanabilirAPPINSIGHTS_INSTRUMENTATIONKEY. Portalda App Service ve Azure İşlevleri için deneyimler, bu ayarları kaynaktan telemetri verilerini görüntülemek için de kullanır. Bu değerlere Key Vault başvuruluyorsa, bu deneyimler kullanılamaz ve bunun yerine telemetriyi görüntülemek için doğrudan Application Insights 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 bu kimlikle oluşturulması ve erişim ilkesinde kullanılabilmesi için önce uygulamanın tanımlanması gerekir.

Aşağıdaki sahte şablon, 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 şekilde davrandıkça bu normalde güvenli olmayan bir davranıştır. Ancak, uygulama ayarını eklediğimizden 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 App Service ortam değişkenleri ve uygulama ayarları.

Anahtar kasası başvurularıyla ilgili sorunları 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ı nedeniyledir. 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ı'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 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

  1. Portalda uygulamanıza gidin.
  2. Sorunları tanılama ve çözme’yi seçin.
  3. Kullanılabilirlik ve Performans'ı ve ardından Web uygulaması kapalı'yı seçin.
  4. Arama kutusunda Key Vault Uygulama Ayarları Tanılama'yı arayın ve seçin.

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

  1. Portalda uygulamanıza gidin.
  2. Platform özellikleri'ne gidin.
  3. Sorunları tanılama ve çözme’yi seçin.
  4. Kullanılabilirlik ve Performans'ı seçin ve İşlev uygulaması kapalı veya hataları bildir'i seçin.
  5. Key Vault Uygulama Ayarları Tanılama'yı seçin.