Gebruik Key Vault verwijzingen voor App Service en Azure FunctionsUse Key Vault references for App Service and Azure Functions

Notitie

Key Vault verwijzingen zijn momenteel niet beschikbaar in Linux-verbruiks abonnementen.Key Vault references are not currently available in Linux consumption plans.

In dit onderwerp wordt beschreven hoe u kunt werken met geheimen van Azure Key Vault in uw App Service of Azure Functions toepassing zonder dat u code wijzigingen hoeft aan te brengen.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 is een service die gecentraliseerd geheimen beheer biedt, met volledige controle over het toegangs beleid en de controle geschiedenis.Azure Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history.

Toegang tot Key Vault verlenen aan uw appGranting your app access to Key Vault

Als u geheimen van Key Vault wilt lezen, moet er een kluis zijn gemaakt en moet u uw app toegang geven tot het bestand.In order to read secrets from Key Vault, you need to have a vault created and give your app permission to access it.

  1. Maak een sleutel kluis door de Key Vault Snelstartgidste volgen.Create a key vault by following the Key Vault quickstart.

  2. Maak een door het systeem toegewezen beheerde identiteit voor uw toepassing.Create a system-assigned managed identity for your application.

    Notitie

    Key Vault verwijzingen worden momenteel alleen door het systeem toegewezen beheerde identiteiten ondersteund.Key Vault references currently only support system-assigned managed identities. Door de gebruiker toegewezen identiteiten kunnen niet worden gebruikt.User-assigned identities cannot be used.

  3. Maak een toegangs beleid in Key Vault voor de toepassings-id die u eerder hebt gemaakt.Create an access policy in Key Vault for the application identity you created earlier. Schakel de geheime machtiging ' Get ' in voor dit beleid.Enable the "Get" secret permission on this policy. Configureer de instellingen voor ' geautoriseerde toepassing ' of applicationId niet, omdat deze niet compatibel is met een beheerde identiteit.Do not configure the "authorized application" or applicationId settings, as this is not compatible with a managed identity.

    Notitie

    Key Vault verwijzingen zijn niet in staat om geheimen op te lossen die zijn opgeslagen in een sleutel kluis met netwerk beperkingen.Key Vault references are not presently able to resolve secrets stored in a key vault with network restrictions.

Verwijzings syntaxisReference syntax

Een Key Vault-verwijzing heeft de vorm @Microsoft.KeyVault({referenceString}), waarbij {referenceString} wordt vervangen door een van de volgende opties:A Key Vault reference is of the form @Microsoft.KeyVault({referenceString}), where {referenceString} is replaced by one of the following options:

Verwijzings reeksReference string BeschrijvingDescription
SecretUri =SecretUriSecretUri=secretUri De SecretUri moet de volledige gegevenslaag URI zijn van een geheim in Key Vault, met inbegrip van een versie, bijvoorbeeld 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
Kluisnaam =kluis; Geheim =geheim; SecretVersion =SecretVersionVaultName=vaultName;SecretName=secretName;SecretVersion=secretVersion De kluisnaam moet de naam van uw Key Vault-resource zijn.The VaultName should the name of your Key Vault resource. De naam van het doel geheim is.The SecretName should be the name of the target secret. De SecretVersion moet de versie zijn van het geheim dat moet worden gebruikt.The SecretVersion should be the version of the secret to use.

Notitie

Er zijn momenteel versies vereist.Versions are currently required. Bij het draaien van geheimen moet u de versie in de configuratie van de toepassing bijwerken.When rotating secrets, you will need to update the version in your application configuration.

Een volledige verwijzing ziet er bijvoorbeeld als volgt uit:For example, a complete reference would look like the following:

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

U kunt ookAlternatively:

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

Instellingen van de bron toepassing van Key VaultSource Application Settings from Key Vault

Key Vault verwijzingen kunnen worden gebruikt als waarden voor Toepassings instellingen, zodat u geheimen in Key Vault in plaats van de site configuratie kunt blijven gebruiken. Toepassings instellingen worden op rest versleuteld, maar als u de mogelijkheden van een geheim beheer nodig hebt, moeten ze in Key Vault gaan.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.

Als u een Key Vault referentie voor een toepassings instelling wilt gebruiken, stelt u de verwijzing in als de waarde van de instelling.To use a Key Vault reference for an application setting, set the reference as the value of the setting. Uw app kan naar het geheim verwijzen via de sleutel normaal.Your app can reference the secret through its key as normal. Er zijn geen code wijzigingen vereist.No code changes are required.

Tip

De meeste toepassings instellingen die gebruikmaken van Key Vault verwijzingen moeten worden gemarkeerd als sleuf instellingen, omdat u voor elke omgeving afzonderlijke kluizen moet hebben.Most application settings using Key Vault references should be marked as slot settings, as you should have separate vaults for each environment.

Implementatie van Azure Resource ManagerAzure Resource Manager deployment

Wanneer u de implementatie van resources via Azure Resource Manager sjablonen automatiseert, moet u mogelijk uw afhankelijkheden in een bepaalde volg orde rangschikken om deze functie te kunnen gebruiken.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. Houd er rekening mee dat u de toepassings instellingen moet definiƫren als hun eigen resource, in plaats van een siteConfig-eigenschap in de site definitie te gebruiken.Of note, you will need to define your application settings as their own resource, rather than using a siteConfig property in the site definition. Dit komt doordat de site eerst moet worden gedefinieerd, zodat de door het systeem toegewezen identiteit wordt gemaakt en kan worden gebruikt in het toegangs beleid.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.

Een voor beeld van een psuedo-sjabloon voor een functie-app kan er als volgt uitzien: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]"
                    }
                }
            ]
        }
    ]
}

Notitie

In dit voor beeld is de bron beheer implementatie afhankelijk van de toepassings instellingen.In this example, the source control deployment depends on the application settings. Dit is normaal gesp roken onveilig gedrag, omdat het bijwerken van de app-instelling asynchroon werkt.This is normally unsafe behavior, as the app setting update behaves asynchronously. Omdat we echter de WEBSITE_ENABLE_SYNC_UPDATE_SITE-toepassings instelling hebben opgenomen, is de update synchroon.However, because we have included the WEBSITE_ENABLE_SYNC_UPDATE_SITE application setting, the update is synchronous. Dit betekent dat de implementatie van broncode beheer alleen begint zodra de instellingen van de toepassing volledig zijn bijgewerkt.This means that the source control deployment will only begin once the application settings have been fully updated.

Problemen met Key Vault verwijzingen oplossenTroubleshooting Key Vault References

Als een verwijzing niet correct wordt opgelost, wordt in plaats daarvan de referentie waarde gebruikt.If a reference is not resolved properly, the reference value will be used instead. Dit betekent dat voor toepassings instellingen een omgevings variabele wordt gemaakt waarvan de waarde de @Microsoft.KeyVault(...)-syntaxis heeft.This means that for application settings, an environment variable would be created whose value has the @Microsoft.KeyVault(...) syntax. Dit kan ertoe leiden dat de toepassing fouten genereert, omdat er een geheim van een bepaalde structuur werd verwacht.This may cause the application to throw errors, as it was expecting a secret of a certain structure.

Dit wordt meestal veroorzaakt door een onjuiste configuratie van het Key Vault- toegangs beleid.Most commonly, this is due to a misconfiguration of the Key Vault access policy. Het kan echter ook worden veroorzaakt door een geheim dat niet meer aanwezig is of een syntaxis fout in de verwijzing zelf.However, it could also be due to a secret no longer existing or a syntax error in the reference itself.

Als de syntaxis juist is, kunt u andere oorzaken voor fouten weer geven door de huidige oplossings status in de portal te controleren.If the syntax is correct, you can view other causes for error by checking the current resolution status in the portal. Navigeer naar toepassings instellingen en selecteer bewerken voor de betreffende verwijzing.Navigate to Application Settings and select "Edit" for the reference in question. Onder de instellings configuratie ziet u status informatie, inclusief eventuele fouten.Below the setting configuration, you should see status information, including any errors. Als deze ontbreken, betekent dit dat de verwijzings syntaxis ongeldig is.The absence of these implies that the reference syntax is invalid.

U kunt ook een van de ingebouwde detectoren gebruiken om aanvullende informatie te krijgen.You can also use one of the built-in detectors to get additional information.

De detector voor App Service gebruikenUsing the detector for App Service

  1. Navigeer in de portal naar uw app.In the portal, navigate to your app.
  2. Selecteer problemen vaststellen en oplossen.Select Diagnose and solve problems.
  3. Kies Beschik baarheid en prestaties en selecteer Web-app lager.Choose Availability and Performance and select Web app down.
  4. Zoek Key Vault diagnostische gegevens over toepassings instellingen en klik op meer informatie.Find Key Vault Application Settings Diagnostics and click More info.

De detector voor Azure Functions gebruikenUsing the detector for Azure Functions

  1. Navigeer in de portal naar uw app.In the portal, navigate to your app.
  2. Navigeer naar platform functies.Navigate to Platform features.
  3. Selecteer problemen vaststellen en oplossen.Select Diagnose and solve problems.
  4. Kies Beschik baarheid en prestaties en selecteer functie-app omlaag of rapportage fouten.Choose Availability and Performance and select Function app down or reporting errors.
  5. Klik op Key Vault diagnostische gegevens over toepassings instellingen.Click on Key Vault Application Settings Diagnostics.