Key Vault-verwijzingen gebruiken als app-instellingen in Azure-app Service en Azure Functions

2025-06-05

In dit artikel leest u hoe u geheimen uit Azure Key Vault gebruikt als waarden van app-instellingen of verbindingsreeksen in uw Azure App Service- of Azure Functions-apps.

Key Vault is een service die gecentraliseerd geheimenbeheer biedt, met volledige controle over toegangsbeleid en controlegeschiedenis. Wanneer een app-instelling of verbindingsreeks een Key Vault-verwijzing is, kan uw toepassingscode deze gebruiken zoals elke andere app-instelling of verbindingsreeks. Op deze manier kunt u geheimen onderhouden, afgezien van de configuratie van uw app. App-instellingen worden veilig versleuteld wanneer ze in rust zijn, maar als u mogelijkheden nodig hebt voor het beheren van geheimen, moeten ze in een sleutelkluis worden opgeslagen.

Uw app toegang verlenen tot een sleutelkluis

Als u geheimen uit een sleutelkluis wilt lezen, moet u eerst een kluis maken en uw app toestemming geven om deze te openen:

Maak een sleutelkluis door de quickstart van Key Vault te volgen.
Maak een beheerde identiteit voor uw toepassing.

Sleutelkluisverwijzingen maken standaard gebruik van de door het systeem toegewezen identiteit van de app, maar u kunt een door de gebruiker toegewezen identiteit opgeven.
Verleen leestoegang tot geheimen in uw sleutelkluis voor de beheerde identiteit die u hebt gemaakt. Hoe u dit doet, is afhankelijk van het machtigingsmodel van uw sleutelkluis:
- Op rollen gebaseerd toegangsbeheer van Azure: wijs de gebruikersrol Key Vault-geheimen toe aan de beheerde identiteit. Zie Toegang bieden tot Key Vault-sleutels, -certificaten en -geheimen met op rollen gebaseerd toegangsbeheer van Azure.
- Toegangsbeleid voor de kluis: wijs de machtiging Ophalen van geheimen toe aan de beheerde identiteit. Zie Toegangsbeleid voor Key Vault toewijzen.

Toegang tot netwerkbeperkte kluizen

Als uw kluis is geconfigureerd met netwerkbeperkingen, moet u ervoor zorgen dat de toepassing netwerktoegang heeft. Kluizen mogen niet afhankelijk zijn van de openbare uitgaande IP-adressen van de app, omdat het IP-adres van de oorsprong van de geheime aanvraag anders kan zijn. In plaats daarvan moet de kluis worden geconfigureerd om verkeer van een virtueel netwerk dat de app gebruikt te accepteren.

Zorg ervoor dat de toepassing uitgaande netwerkmogelijkheden heeft geconfigureerd, zoals beschreven in App Service-netwerkfuncties en Azure Functions-netwerkopties.

Op dit moment moeten Linux-toepassingen die verbinding maken met privé-eindpunten expliciet worden geconfigureerd om al het verkeer via het virtuele netwerk te routeren. Voer de volgende opdracht uit om deze instelling te configureren:
- 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}
```
Zorg ervoor dat de configuratie van de kluis het netwerk of subnet toestaat dat uw app gebruikt voor toegang.

Houd er rekening mee dat zelfs als u de kluis juist hebt geconfigureerd om verkeer van uw virtuele netwerk te accepteren, de kluislogboeken nog steeds een gefaalde 403-Verboden SecretGet-gebeurtenis van het openbare uitgaande IP-adres van de app kunnen weergeven. Dit wordt gevolgd door een geslaagde SecretGet-gebeurtenis van het privé-IP-adres van de app en is standaard.

Toegang tot kluizen met een door een gebruiker toegewezen identiteit

Sommige apps moeten tijdens het maken verwijzen naar geheimen wanneer een door het systeem toegewezen identiteit nog niet beschikbaar is. In deze gevallen moet u een gebruikersidentiteit maken en deze van tevoren toegang tot de kluis geven.

Nadat u machtigingen hebt verleend aan de door de gebruiker toegewezen identiteit, voert u de volgende stappen uit:

Wijs de identiteit toe aan uw toepassing.

Configureer de app voor het gebruik van deze identiteit voor Key Vault-referentiebewerkingen door de keyVaultReferenceIdentity eigenschap in te stellen op de resource-id van de door de gebruiker toegewezen identiteit:

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'}}"

Deze instelling is van toepassing op alle Key Vault-verwijzingen voor de app.

Inzicht in rotatie

Als de geheime versie niet is opgegeven in de verwijzing, gebruikt de app de nieuwste versie die in de sleutelkluis aanwezig is. Wanneer nieuwere versies beschikbaar komen, zoals bij rotatie, wordt de app automatisch bijgewerkt en wordt de nieuwste versie binnen 24 uur gebruikt.

De vertraging is omdat App Service de waarden van de Key Vault-verwijzingen in de cache opslaat en ze elke 24 uur opnieuw in de cache opslaat. Elke configuratiewijziging aan de app zorgt ervoor dat de app opnieuw wordt opgestart en dat alle genoemde geheimen onmiddellijk opnieuw worden opgehaald.

Als u de sleutelkluisverwijzingen van uw app wilt afdwingen, moet u een geverifieerde POST-aanvraag indienen bij het API-eindpunt https://management.azure.com/[Resource ID]/config/configreferences/appsettings/refresh?api-version=2022-03-01.

Informatie over de instellingen van de bron-app uit Key Vault

Als u een Key Vault-verwijzing wilt gebruiken, stelt u de verwijzing in als de waarde van de instelling. Uw app kan naar het geheim verwijzen via de bijbehorende sleutel zoals gewoonlijk. Er zijn geen codewijzigingen vereist.

Aanbeveling

Omdat u voor elke omgeving afzonderlijke kluizen moet hebben, moeten de meeste app-instellingen die gebruikmaken van Key Vault-verwijzingen worden gemarkeerd als slotinstellingen.

Een Key Vault-verwijzing is van de vorm @Microsoft.KeyVault({referenceString}), waar {referenceString} zich in een van de volgende indelingen bevindt.

Referentiestring	Beschrijving
`SecretUri=<secretUri>`	Dit `SecretUri` moet de volledige gegevensvlak-URI van een geheim in de kluis zijn. Bijvoorbeeld: `https://myvault.vault.azure.net/secrets/mysecret`. Voeg eventueel een versie toe, zoals `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`.
`VaultName=<vaultName>;SecretName=<secretName>`;`SecretVersion=<secretVersion>`	De waarde `VaultName` is vereist en is de naam van de kluis. De `SecretName` waarde is vereist en is de geheime naam. De `SecretVersion` waarde is optioneel, maar geeft, indien aanwezig, de versie van het geheim aan die moet worden gebruikt.

Een volledige verwijzing zonder een specifieke versie ziet er bijvoorbeeld uit als de volgende tekenreeks:

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

U kunt ook het volgende doen:

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

Overwegingen voor het koppelen van Azure Files

Apps kunnen de WEBSITE_CONTENTAZUREFILECONNECTIONSTRING toepassingsinstelling gebruiken om Azure Files als bestandssysteem te koppelen. Deze instelling bevat validatiecontroles om ervoor te zorgen dat de app correct kan worden gestart.

Het platform is afhankelijk van een inhoudsdeling in Azure Files. Het platform gaat ervan uit dat er een standaardnaam wordt opgegeven, tenzij er een is opgegeven met behulp van de WEBSITE_CONTENTSHARE instelling. Voor aanvragen die deze instellingen wijzigen, valideert het platform dat deze inhoudsshare bestaat. Als de inhoudsshare niet bestaat, probeert het platform deze te maken. Als het platform de inhoudsshare niet kan vinden of maken, wordt de aanvraag geblokkeerd.

Wanneer u Key Vault-verwijzingen in deze instelling gebruikt, mislukt de validatiecontrole standaard omdat het geheim niet kan worden opgelost tijdens de verwerking van de binnenkomende aanvraag. U kunt dit probleem voorkomen door de validatie over te slaan door de instelling in te stellen WEBSITE_SKIP_CONTENTSHARE_VALIDATION op 1. Met deze instelling moet App Service alle controles omzeilen en wordt de inhoudsshare niet voor u gemaakt. Zorg ervoor dat de inhoudsdeling van tevoren wordt gemaakt.

Let op

Als u de validatie overslaat en de verbindingsreeks of de inhoudsshare ongeldig is, start de app niet goed en worden HTTP 500-fouten gemaakt.

Als onderdeel van het maken van de app kan het koppelen van de inhoudsdeling mislukken omdat machtigingen voor beheerde identiteiten niet worden doorgegeven of omdat de integratie van het virtuele netwerk niet correct is ingesteld. U kunt het instellen van Azure Files uitstellen tot later in de implementatiesjabloon om dit gedrag mogelijk te maken. Zie de Implementatie van Azure Resource Manager verderop in dit artikel voor meer informatie.

In dit geval gebruikt App Service een standaardbestandssysteem totdat Azure Files is ingesteld en bestanden niet worden gekopieerd. U moet ervoor zorgen dat er tijdens de tussentijdse periode geen implementatiepogingen worden uitgevoerd voordat Azure Files wordt gekoppeld.

Overwegingen voor Application Insights-instrumentatie

Apps kunnen de APPINSIGHTS_INSTRUMENTATIONKEY of APPLICATIONINSIGHTS_CONNECTION_STRING toepassingsinstellingen gebruiken om te integreren met Application Insights.

Voor App Service en Azure Functions gebruikt Azure Portal deze instellingen ook om telemetriegegevens van de resource weer te geven. Als er vanuit Key Vault naar deze waarden wordt verwezen, is deze methode niet beschikbaar. In plaats daarvan moet u rechtstreeks met de Application Insights-resource werken om de telemetrie weer te geven. Deze waarden worden echter niet beschouwd als geheimen, dus u kunt overwegen ze rechtstreeks te configureren in plaats van Key Vault-verwijzingen te gebruiken.

Implementatie van Azure Resource Manager

Wanneer u resource-implementaties automatiseert via Azure Resource Manager-sjablonen, moet u mogelijk uw afhankelijkheden in een bepaalde volgorde rangschikken. Zorg ervoor dat u uw app-instellingen definieert als hun eigen resource, in plaats van een siteConfig eigenschap in de app-definitie te gebruiken. De app moet eerst worden gedefinieerd, zodat met het definiëren van de app de door het systeem toegewezen identiteit wordt gecreëerd en kan worden gebruikt in het toegangsbeleid.

De volgende pseudosjabloon is een voorbeeld van hoe een functie-app eruit kan zien:

{
    //...
    "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]"
                    }
                }
            ]
        }
    ]
}

Notitie

In dit voorbeeld is de implementatie van broncodebeheer afhankelijk van de toepassingsinstellingen. Deze afhankelijkheid is normaal gesproken onveilig, omdat de update van de app-instelling asynchroon werkt. Omdat u echter de WEBSITE_ENABLE_SYNC_UPDATE_SITE toepassingsinstelling hebt opgenomen, is de update synchroon. De implementatie van broncodebeheer begint pas nadat de toepassingsinstellingen volledig zijn bijgewerkt. Zie Omgevingsvariabelen en app-instellingen in Azure-app Service voor meer app-instellingen.

Problemen met Key Vault-verwijzingen oplossen

Als een verwijzing niet correct wordt opgelost, wordt in plaats daarvan de referentiestring gebruikt, bijvoorbeeld @Microsoft.KeyVault(...). Deze situatie kan ertoe leiden dat de toepassing fouten genereert, omdat er een geheim van een andere waarde wordt verwacht.

Het niet oplossen is meestal te wijten aan een onjuiste configuratie van het key vault-toegangsbeleid. De reden kan echter ook zijn dat er geen geheim meer bestaat of dat de verwijzing een syntaxisfout bevat.

Als de syntaxis juist is, kunt u andere oorzaken van een fout bekijken door de huidige oplossingsstatus in Azure Portal te controleren. Ga naar Toepassingsinstellingen en selecteer Bewerken voor de betreffende verwijzing. Het bewerkingsdialoogvenster bevat statusinformatie, inclusief eventuele fouten. Als u het statusbericht niet ziet, betekent dit dat de syntaxis ongeldig is en niet wordt herkend als key vault-verwijzing.

U kunt ook een van de ingebouwde detectoren gebruiken om meer informatie te krijgen.

De detector voor App Service gebruiken:

Ga in Azure Portal naar uw app.
Selecteer Problemen diagnosticeren en oplossen.
Selecteer Beschikbaarheid en Prestaties>Web-app niet beschikbaar.
Zoek in het zoekvak naar en selecteer Key Vault Application Settings Diagnostics.

De detector voor Azure Functions gebruiken:

Ga in Azure Portal naar uw app.
Ga naar Platformfuncties.
Selecteer Problemen diagnosticeren en oplossen.
Selecteer Beschikbaarheid en prestaties>Functie-app is niet beschikbaar of rapporteert fouten.
Selecteer Diagnostische gegevens van Key Vault-toepassingsinstellingen.