Gebruik Key Vault verwijzingen als app-instellingen in Azure App Service, Azure Functions en Azure Logic Apps (Standard)

In dit artikel wordt beschreven hoe u geheimen uit Azure Key Vault gebruikt als waarden in appinstellingen of connectiontekenreeksen voor apps die zijn gemaakt met Azure App Service, Azure Functions of Azure Logic Apps (Standard).

Key Vault is een service die gecentraliseerd geheimenbeheer biedt, met volledige controle over toegangsbeleid en controlegeschiedenis. Wanneer een app-instelling of connectiestring een verwijzing naar Key Vault is, kan uw applicatiecode deze gebruiken zoals elke andere app-instelling of connectiestring. 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:

1. Maak een key vault door de quickstart Key Vault te volgen.

2. 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.

3. 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:

   • Azure op rollen gebaseerd toegangsbeheer: wijs de rol Key Vault Geheimengebruiker toe aan de beheerde identiteit. Zie Toegang tot Key Vault sleutels, certificaten en geheimen met Azure op rollen gebaseerd toegangsbeheer.
   • Toegangsbeleid voor de kluis: wijs de machtiging Ophalen van geheimen toe aan de beheerde identiteit. Zie Toegang beleidslijn 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.

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

   Met uitzondering van functie-apps die worden uitgevoerd in het Flex Consumption-abonnement, moeten Linux-toepassingen die verbinding maken met privé-eindpunten expliciet worden geconfigureerd om al het verkeer via het virtuele netwerk te routeren. Wanneer u een Flex Consumption-abonnement uitvoert, wordt deze routering automatisch uitgevoerd en is er geen aanvullende configuratie vereist. Voer de volgende opdracht uit om routering van virtuele netwerken te configureren door vnetRouteAllEnabled in te stellen op true:

   • Azure CLI
   • Azure PowerShell

   az webapp config set --resource-group <group-name>  --subscription <subscription> --name <app-name> --generic-configurations '{"vnetRouteAllEnabled": true}'
   

2. 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:

1. Wijs de identiteit toe aan uw toepassing.

2. Configureer de app voor het gebruik van deze identiteit voor Key Vault referentiebewerkingen door de eigenschap keyVaultReferenceIdentity 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}
   

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 oplossing van de Key Vault verwijzingen 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.

Inzicht in 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.

Een Key Vault verwijzing is van het formulier @Microsoft.KeyVault({referenceString}), waarbij {referenceString} een van de volgende indelingen heeft:

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 toepassingsinstelling WEBSITE_CONTENTAZUREFILECONNECTIONSTRING 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 beschikken over een inhoudsdeling binnen 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.

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 aan te passen. Zie Azure Resource Manager-implementatie 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 de 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 aren 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 sequentieren. 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]"
                    }
                }
            ]
        }
    ]
}

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 kunnen oplossen is vaak 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 de 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 een Key Vault verwijzing.

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

De detector voor App Service gebruiken:

1. Ga in de Azure-portal naar uw app.
2. Selecteer Problemen diagnosticeren en oplossen.
3. Selecteer Beschikbaarheid en Prestaties>Web-app niet beschikbaar.
4. In het zoekvak, zoek naar en selecteer Key Vault Application Settings Diagnostics.

De detector voor Azure Functions gebruiken:

1. Ga in de Azure-portal naar uw app.
2. Ga naar Platformfuncties.
3. Selecteer Problemen diagnosticeren en oplossen.
4. Selecteer Beschikbaarheid en prestaties>Functie-app is niet beschikbaar of rapporteert fouten.
5. Selecteer Key Vault Diagnostische gegevens over toepassingsinstellingen.