Key Vault-verwijzingen gebruiken als app-instellingen in Azure-app Service en Azure Functions
Notitie
Vanaf 1 juni 2024 hebben alle nieuw gemaakte App Service-apps de mogelijkheid om een unieke standaardhostnaam te genereren met behulp van de naamconventie <app-name>-<random-hash>.<region>.azurewebsites.net. Bestaande app-namen blijven ongewijzigd.
Voorbeeld: myapp-ds27dh7271aah175.westus-01.azurewebsites.net
Raadpleeg de unieke standaardhostnaam voor App Service-resource voor meer informatie.
In dit artikel leest u hoe u geheimen uit Azure Key Vault gebruikt als waarden van app-instellingen of verbindingsreeks s in uw App Service- of Azure Functions-apps.
Azure Key Vault is een service die gecentraliseerd geheimenbeheer biedt, met volledige controle over toegangsbeleid en controlegeschiedenis. Wanneer een app-instelling of verbindingsreeks een sleutelkluisverwijzing 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 in rust versleuteld, maar als u mogelijkheden voor geheimbeheer nodig hebt, moeten ze naar een sleutelkluis gaan.
Uw app toegang verlenen tot een sleutelkluis
Als u geheimen uit een sleutelkluis wilt lezen, moet u een kluis hebben gemaakt 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.
Autoriseer leestoegang tot geheimen in uw sleutelkluis voor de beheerde identiteit die u eerder 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 verlenen tot Key Vault-sleutels, -certificaten en -geheimen met een op rollen gebaseerd toegangsbeheer van Azure voor instructies.
- Toegangsbeleid voor de kluis: wijs de machtiging Geheimen ophalen toe aan de beheerde identiteit. Zie Toegangsbeleid voor Key Vault toewijzen voor instructies.
Toegang tot kluizen met beperkte netwerkrechten
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 oorspronkelijke IP-adres van de geheime aanvraag anders kan zijn. In plaats daarvan moet de kluis worden geconfigureerd om verkeer van een virtueel netwerk te accepteren 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.
Linux-toepassingen die verbinding maken met privé-eindpunten, moeten expliciet worden geconfigureerd om al het verkeer via het virtuele netwerk te routeren. Deze vereiste wordt verwijderd in een toekomstige update. Voer de volgende opdracht uit om deze instelling te configureren:
az webapp config set --subscription <sub> -g <group-name> -n <app-name> --generic-configurations '{"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 kan een door de gebruiker toegewezen identiteit worden gemaakt en vooraf toegang krijgen tot de kluis.
Nadat u machtigingen hebt verleend voor 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
keyVaultReferenceIdentityeigenschap in te stellen op de resource-id van de door de gebruiker toegewezen identiteit.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}
Deze instelling is van toepassing op alle sleutelkluisverwijzingen voor de app.
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 komt doordat App Service de waarden van de sleutelkluisverwijzingen in de cache opslaat en deze elke 24 uur opnieuw ophaalt. Elke configuratiewijziging in de app zorgt ervoor dat de app opnieuw wordt opgestart en dat alle geheimen waarnaar wordt verwezen, onmiddellijk opnieuw worden opgestart.
Instellingen voor bron-apps uit de sleutelkluis
Als u een sleutelkluisverwijzing wilt gebruiken, stelt u de verwijzing in als de waarde van de instelling. Uw app kan naar het geheim verwijzen via de bijbehorende sleutel als normaal. Er zijn geen codewijzigingen vereist.
Tip
De meeste app-instellingen die gebruikmaken van key vault-verwijzingen, moeten worden gemarkeerd als site-instellingen, omdat u afzonderlijke kluizen voor elke omgeving moet hebben.
Een sleutelkluisverwijzing is van het formulier @Microsoft.KeyVault({referenceString}), waarin {referenceString} zich een van de volgende indelingen bevindt:
| Verwijzingstekenreeks | Beschrijving |
|---|---|
| SecretUri=secretUri | De SecretUri moet bijvoorbeeld de volledige gegevensvlak-URI van een geheim in de kluis https://myvault.vault.azure.net/secrets/mysecretzijn. Voeg eventueel een versie toe, zoals https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931. |
| VaultName=vaultName; SecretName=secretName; SecretVersion=secretVersion | VaultName is vereist en is de kluisnaam. De SecretName is vereist en is de geheime naam. De SecretVersion is optioneel, maar als aanwezig de versie van het geheim aangeeft 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 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 en probeert het te maken als dat niet het geval is. Als de inhoudsshare niet kan worden gevonden of gemaakt, wordt de aanvraag geblokkeerd.
Wanneer u sleutelkluisverwijzingen in deze instelling gebruikt, mislukt de validatiecontrole standaard omdat het geheim zelf niet kan worden omgezet tijdens het verwerken van de binnenkomende aanvraag. U kunt dit probleem voorkomen door de validatie over te slaan door 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 deze vooraf is gemaakt.
Let op
Als u de validatie overslaat en de verbindingsreeks of inhoudsshare ongeldig is, kan de app niet goed worden gestart en worden alleen HTTP 500-fouten weergegeven.
Als onderdeel van het maken van de app kan het koppelen van de inhoudsshare mislukken omdat machtigingen voor beheerde identiteiten niet worden doorgegeven of dat de integratie van het virtuele netwerk niet is ingesteld. U kunt het instellen van Azure Files uitstellen tot later in de implementatiesjabloon om dit mogelijk te maken. Zie Azure Resource Manager-implementatie 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 ze ook rechtstreeks configureren in plaats van sleutelkluisverwijzingen 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. Dit komt doordat de app eerst moet 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. Dit is normaal gesproken onveilig gedrag, omdat de update van de app-instelling zich asynchroon gedraagt. Omdat we echter de WEBSITE_ENABLE_SYNC_UPDATE_SITE toepassingsinstelling hebben opgenomen, is de update synchroon. Dit betekent dat de implementatie van broncodebeheer pas begint zodra de toepassingsinstellingen volledig zijn bijgewerkt. Zie Omgevingsvariabelen en app-instellingen in Azure-app Service voor meer app-instellingen.
Problemen met sleutelkluisverwijzingen oplossen
Als een verwijzing niet juist is opgelost, wordt de verwijzingstekenreeks gebruikt (bijvoorbeeld @Microsoft.KeyVault(...)). Dit kan ertoe leiden dat de toepassing fouten genereert, omdat er een geheim van een andere waarde wordt verwacht.
Het oplossen van fouten is meestal het gevolg van een onjuiste configuratie van het key vault-toegangsbeleid. Dit kan echter ook het gevolg zijn van een geheim dat niet meer bestaat of een syntaxisfout in de verwijzing zelf.
Als de syntaxis juist is, kunt u andere oorzaken van fouten bekijken door de huidige oplossingsstatus in de portal te controleren. Navigeer 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 sleutelkluisverwijzing.
U kunt ook een van de ingebouwde detectoren gebruiken om aanvullende informatie op te halen.
De detector voor App Service gebruiken
- Navigeer in de portal naar uw app.
- Selecteer Problemen vaststellen en oplossen.
- Kies Beschikbaarheid en prestaties en selecteer web-app omlaag.
- Zoek en selecteer in het zoekvak diagnostische gegevens over Key Vault-toepassingsinstellingen.
De detector voor Azure Functions gebruiken
- Navigeer in de portal naar uw app.
- Ga naar Platformfuncties.
- Selecteer Problemen vaststellen en oplossen.
- Kies Beschikbaarheid en prestaties en selecteer Functie-app niet beschikbaar of rapporteer fouten.
- Selecteer Diagnostische gegevens van Key Vault-toepassingsinstellingen.