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

Artikel
05/21/2024

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:
- 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 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 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 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 de volledige gegevensvlak-URI van een geheim in de kluis zijn, eventueel inclusief een versie, bijvoorbeeld `https://myvault.vault.azure.net/secrets/mysecret/` of `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 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 toepassings Instellingen 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 Key Vault Application Instellingen Diagnostics in het zoekvak.

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 Key Vault-toepassing Instellingen Diagnostics.

Share via