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

Artikel
04/07/2025

Notitie

Vanaf 1 juni 2024 kunnen nieuw gemaakte App Service-apps een unieke standaardhostnaam genereren die gebruikmaakt van de naamconventie <app-name>-<random-hash>.<region>.azurewebsites.net. Voorbeeld: myapp-ds27dh7271aah175.westus-01.azurewebsites.net. Bestaande app-namen blijven ongewijzigd.

Zie het blogbericht over het maken van een web-app met een unieke standaardhostnaamvoor meer informatie.

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 voor instructies.
- Toegangsbeleid voor de kluis: wijs de machtiging Ophalen van geheimen toe aan de beheerde identiteit. Zie voor instructies Een 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 moeten niet afhankelijk zijn van de openbare uitgaande IP-adressen van de app, omdat het bron-IP-adres van de aanvraag om geheime gegevens anders kan zijn. In plaats daarvan moet de kluis worden geconfigureerd om verkeer te accepteren van een virtueel netwerk dat door de app wordt gebruikt.

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 --subscription <sub> -g <group-name> -n <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.

Toegang tot kluizen met een door de 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 kunt u een door de gebruiker toegewezen identiteit maken en deze vooraf toegang geven tot de kluis.

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 als u dat nog niet hebt gedaan.

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 MyUserAssignedIdentityName | 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 een rotatie-gebeurtenis, 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.

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.

Tip

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

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, `https://myvault.vault.azure.net/secrets/mysecret`bijvoorbeeld. Voeg eventueel een versie toe, zoals `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`.
`VaultName=<vaultName>;SecretName=<secretName>`;`SecretVersion=<secretVersion>`	De `VaultName` waarde is vereist en is de kluisnaam. 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 het hebben van een inhoudsshare in Azure Files en er wordt uitgegaan van een standaardnaam, tenzij er een is opgegeven via de WEBSITE_CONTENTSHARE instelling. Voor aanvragen die deze instellingen wijzigen, valideert het platform of 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 inhoudsshare van tevoren wordt gemaakt.

Let op

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

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.

De portal-ervaringen voor App Service en Azure Functions gebruiken deze instellingen ook om telemetriegegevens van de resource weer te geven. Als er vanuit Key Vault naar deze waarden wordt verwezen, zijn deze ervaringen niet beschikbaar en moet u in plaats daarvan 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 om deze functie te laten werken. 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 de door het systeem toegewezen identiteit wordt gemaakt 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 we echter de WEBSITE_ENABLE_SYNC_UPDATE_SITE toepassingsinstelling hebben 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 verwijzingstekst 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 fouten bekijken door de huidige oplossingsstatus in de 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 aanvullende informatie op te halen.

De detector voor App Service gebruiken:

Ga in de 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 de 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.

Delen via