App Service ve Azure Işlevleri için Key Vault başvurularını kullanmaUse Key Vault references for App Service and Azure Functions

Not

Key Vault başvuruları Linux tüketim planlarında Şu anda kullanılamıyor.Key Vault references are not currently available in Linux consumption plans.

Bu konu başlığı altında, herhangi bir kod değişikliğine gerek kalmadan App Service veya Azure Işlevleri uygulamanızda Azure Key Vault gizliliklerle nasıl çalışılacağı gösterilmektedir.This topic shows you how to work with secrets from Azure Key Vault in your App Service or Azure Functions application without requiring any code changes. Azure Key Vault , erişim ilkeleri ve denetim geçmişi üzerinde tam denetim ile merkezi gizli dizi yönetimi sağlayan bir hizmettir.Azure Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history.

Uygulamanıza Key Vault erişim vermeGranting your app access to Key Vault

Key Vault parolaları okumak için bir kasasının oluşturulmuş olması ve uygulamanıza erişim izni vermeniz gerekir.In order to read secrets from Key Vault, you need to have a vault created and give your app permission to access it.

  1. Key Vault hızlıbaşlangıcı ' nı izleyerek bir Anahtar Kasası oluşturun.Create a key vault by following the Key Vault quickstart.

  2. Uygulamanız için sistem tarafından atanan bir yönetilen kimlik oluşturun.Create a system-assigned managed identity for your application.

    Not

    Key Vault başvurular Şu anda yalnızca sistem tarafından atanan yönetilen kimlikleri destekler.Key Vault references currently only support system-assigned managed identities. Kullanıcı tarafından atanan kimlikler kullanılamaz.User-assigned identities cannot be used.

  3. Daha önce oluşturduğunuz uygulama kimliği için Key Vault bir erişim ilkesi oluşturun.Create an access policy in Key Vault for the application identity you created earlier. Bu ilkede "Get" gizli anahtarını etkinleştirin.Enable the "Get" secret permission on this policy. "Yetkilendirilmiş uygulama" veya applicationId ayarlarını, yönetilen bir kimlikle uyumlu olmadığından yapılandırmayın.Do not configure the "authorized application" or applicationId settings, as this is not compatible with a managed identity.

    Not

    Key Vault başvurular Şu anda ağ kısıtlamalarınasahip bir anahtar kasasında depolanan gizli dizileri çözemeyebilir.Key Vault references are not presently able to resolve secrets stored in a key vault with network restrictions.

Başvuru sözdizimiReference syntax

Key Vault bir başvuru, {referenceString} aşağıdaki seçeneklerden biriyle değiştirildiği @Microsoft.KeyVault({referenceString})formundadır:A Key Vault reference is of the form @Microsoft.KeyVault({referenceString}), where {referenceString} is replaced by one of the following options:

Başvuru dizesiReference string AçıklamaDescription
SecretUri =SecreturiSecretUri=secretUri Secreturi , bir sürüm gibi Key Vault bir parolanın tam veri düzlemi URI 'si olmalıdır, örneğin, https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931The SecretUri should be the full data-plane URI of a secret in Key Vault, including a version, e.g., https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931
VaultName =vaultname; SecretName =secretname; SecretVersion =SecretversionVaultName=vaultName;SecretName=secretName;SecretVersion=secretVersion Vaultname Key Vault kaynağınızın adı olmalıdır.The VaultName should the name of your Key Vault resource. Secretname , hedef parolanın adı olmalıdır.The SecretName should be the name of the target secret. Secretversion , kullanılacak gizli dizinin sürümü olmalıdır.The SecretVersion should be the version of the secret to use.

Örneğin, sürüme sahip bir tüm başvuru aşağıdaki gibi görünür:For example, a complete reference with Version would look like the following:

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

KopyalamaktırAlternatively:

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

Key Vault kaynak uygulama ayarlarıSource Application Settings from Key Vault

Key Vault başvuruları, uygulama ayarlarıiçin değer olarak kullanılabilir, böylece gizli dizileri site yapılandırması yerine Key Vault tutabilirsiniz. Uygulama ayarları, bekleyen olarak güvenli bir şekilde şifrelenir, ancak gizli yönetim özelliklerine ihtiyacınız varsa, Key Vault gitmeleri gerekir.Key Vault references can be used as values for Application Settings, allowing you to keep secrets in Key Vault instead of the site config. Application Settings are securely encrypted at rest, but if you need secret management capabilities, they should go into Key Vault.

Bir uygulama ayarı için Key Vault başvurusu kullanmak için, başvuruyu ayarın değeri olarak ayarlayın.To use a Key Vault reference for an application setting, set the reference as the value of the setting. Uygulamanız gizli dizi anahtarı aracılığıyla gizli dizi başvurusu yapabilir.Your app can reference the secret through its key as normal. Kod değişikliği gerekli değildir.No code changes are required.

İpucu

Key Vault başvurularını kullanan uygulama ayarlarının çoğu, her ortam için ayrı kasaların olması gerektiği için yuva ayarları olarak işaretlenmelidir.Most application settings using Key Vault references should be marked as slot settings, as you should have separate vaults for each environment.

Azure Resource Manager dağıtımıAzure Resource Manager deployment

Kaynak dağıtımlarını Azure Resource Manager şablonları aracılığıyla otomatikleştirmede, bu özelliğin çalışmasını sağlamak için bağımlılıklarınızı belirli bir sırada sıraya almanız gerekebilir.When automating resource deployments through Azure Resource Manager templates, you may need to sequence your dependencies in a particular order to make this feature work. Bu durumda, site tanımında siteConfig özelliği kullanmak yerine uygulama ayarlarınızı kendi kaynakları olarak tanımlamanız gerekir.Of note, you will need to define your application settings as their own resource, rather than using a siteConfig property in the site definition. Bunun nedeni, sitenin, sistem tarafından atanan kimliğin birlikte oluşturulması ve erişim ilkesinde kullanılabilmesi için önce tanımlanması gerekir.This is because the site needs to be defined first so that the system-assigned identity is created with it and can be used in the access policy.

Bir işlev uygulaması için örnek bir psuedo şablonu, aşağıdaki gibi görünebilir:An example psuedo-template for a function app might look like the following:

{
    //...
    "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(concat('Microsoft.Web/sites/',  variables('functionAppName'), '/providers/Microsoft.ManagedIdentity/Identities/default'), '2015-08-31-PREVIEW').tenantId]",
                        "objectId": "[reference(concat('Microsoft.Web/sites/',  variables('functionAppName'), '/providers/Microsoft.ManagedIdentity/Identities/default'), '2015-08-31-PREVIEW').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'),'2015-05-01-preview').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')), '2015-05-01').InstrumentationKey]"
                    }
                }
            ]
        }
    ]
}

Not

Bu örnekte, kaynak denetimi dağıtımı uygulama ayarlarına bağlıdır.In this example, the source control deployment depends on the application settings. Uygulama ayarı güncelleştirmesi zaman uyumsuz olarak davrandığı için bu durum normalde güvenli olmayan bir davranıştır.This is normally unsafe behavior, as the app setting update behaves asynchronously. Ancak WEBSITE_ENABLE_SYNC_UPDATE_SITE uygulama ayarını eklediğimiz için güncelleştirme zaman uyumludur.However, because we have included the WEBSITE_ENABLE_SYNC_UPDATE_SITE application setting, the update is synchronous. Bu, kaynak denetimi dağıtımının yalnızca uygulama ayarları tamamen güncelleştirildikten sonra başlayacağı anlamına gelir.This means that the source control deployment will only begin once the application settings have been fully updated.

Key Vault başvuruları sorunlarını gidermeTroubleshooting Key Vault References

Bir başvuru düzgün çözümlenmezse, bunun yerine başvuru değeri kullanılacaktır.If a reference is not resolved properly, the reference value will be used instead. Bu, uygulama ayarları için, değeri @Microsoft.KeyVault(...) sözdizimine sahip olan bir ortam değişkeni oluşturulacak anlamına gelir.This means that for application settings, an environment variable would be created whose value has the @Microsoft.KeyVault(...) syntax. Bu, belirli bir yapının gizli dizisi beklediği için uygulamanın hata oluşturmasına neden olabilir.This may cause the application to throw errors, as it was expecting a secret of a certain structure.

En yaygın olarak, bunun nedeni Key Vault erişim ilkesininyanlış yapılandırılmasından kaynaklanır.Most commonly, this is due to a misconfiguration of the Key Vault access policy. Bununla birlikte, aynı zamanda bir gizli dizi yok veya başvurunun kendisi bir sözdizimi hatası olabilir.However, it could also be due to a secret no longer existing or a syntax error in the reference itself.

Sözdizimi doğruysa, portaldaki geçerli çözüm durumunu denetleyerek hata nedenlerini görüntüleyebilirsiniz.If the syntax is correct, you can view other causes for error by checking the current resolution status in the portal. Uygulama ayarları ' na gidin ve söz konusu başvuru için "Düzenle" seçeneğini belirleyin.Navigate to Application Settings and select "Edit" for the reference in question. Ayar yapılandırmasının altında hatalar da dahil olmak üzere durum bilgilerini görmeniz gerekir.Below the setting configuration, you should see status information, including any errors. Bunun yokluğu, başvuru sözdiziminin geçersiz olduğunu gösterir.The absence of these implies that the reference syntax is invalid.

Ek bilgi edinmek için yerleşik algılayıcıları da kullanabilirsiniz.You can also use one of the built-in detectors to get additional information.

App Service için algılayıcısının kullanımıUsing the detector for App Service

  1. Portalda uygulamanıza gidin.In the portal, navigate to your app.
  2. Tanıla ve sorunları çöz ' ü seçin.Select Diagnose and solve problems.
  3. Kullanılabilirlik ve performans ' ı seçin ve Web uygulaması ' nı seçin.Choose Availability and Performance and select Web app down.
  4. Uygulama ayarları tanılamayı Key Vault bulun ve daha fazla bilgi'ye tıklayın.Find Key Vault Application Settings Diagnostics and click More info.

Azure Işlevleri için algılayıcısının kullanımıUsing the detector for Azure Functions

  1. Portalda uygulamanıza gidin.In the portal, navigate to your app.
  2. Platform özellikleri ' ne gidin.Navigate to Platform features.
  3. Tanıla ve sorunları çöz ' ü seçin.Select Diagnose and solve problems.
  4. Kullanılabilirlik ve performans ' ı seçin ve işlev uygulaması çalışmıyor veya raporlama hataları ' nı seçin.Choose Availability and Performance and select Function app down or reporting errors.
  5. Uygulama ayarları tanılamayı Key Vault ' ye tıklayın.Click on Key Vault Application Settings Diagnostics.