De API- en runtimeversies van App Service-verificatie beheren

Artikel
10/18/2023

In dit artikel leest u hoe u de API- en runtimeversies van de ingebouwde verificatie en autorisatie in App Service kunt aanpassen.

Er zijn twee versies van de beheer-API voor App Service-verificatie. De V2-versie is vereist voor de verificatie-ervaring in Azure Portal. Een app die al gebruikmaakt van de V1-API, kan een upgrade uitvoeren naar de V2-versie zodra er enkele wijzigingen zijn aangebracht. Met name de geheime configuratie moet worden verplaatst naar instellingen voor sleufgebonden toepassingen. Dit kan automatisch worden gedaan vanuit de sectie 'Verificatie' van de portal voor uw app.

De configuratieversie bijwerken

Waarschuwing

Migratie naar V2 schakelt het beheer van de functie App Service-verificatie/autorisatie voor uw toepassing uit via sommige clients, zoals de bestaande ervaring in Azure Portal, Azure CLI en Azure PowerShell. Dit kan niet worden omgekeerd.

De V2-API biedt geen ondersteuning voor het maken of bewerken van Microsoft-account als een afzonderlijke provider, zoals is gedaan in V1. In plaats daarvan wordt het geconvergeerde Microsoft Identity Platform gebruikt om gebruikers aan te melden met zowel Microsoft Entra- als persoonlijke Microsoft-accounts. Wanneer u overschakelt naar de V2-API, wordt de V1 Microsoft Entra-configuratie gebruikt om de Microsoft Identity Platform-provider te configureren. De V1 Microsoft-accountprovider wordt doorgevoerd in het migratieproces en blijft gewoon werken, maar u moet overstappen op het nieuwere Microsoft Identity Platform-model. Zie Ondersteuning voor registraties van Microsoft-accountproviders voor meer informatie.

Het geautomatiseerde migratieproces verplaatst providergeheimen naar toepassingsinstellingen en converteert vervolgens de rest van de configuratie naar de nieuwe indeling. De automatische migratie gebruiken:

Navigeer naar uw app in de portal en selecteer de menuoptie Verificatie .
Als de app is geconfigureerd met het V1-model, ziet u een knop Upgrade .
Controleer de beschrijving in de bevestigingsprompt. Als u klaar bent om de migratie uit te voeren, selecteert u Upgrade in de prompt.

De migratie handmatig beheren

Met de volgende stappen kunt u de toepassing handmatig migreren naar de V2-API als u de hierboven genoemde automatische versie niet wilt gebruiken.

Geheimen verplaatsen naar toepassingsinstellingen

Haal uw bestaande configuratie op met behulp van de V1-API:
```
az webapp auth show -g <group_name> -n <site_name>
```
Noteer in de resulterende JSON-nettolading de geheime waarde die wordt gebruikt voor elke provider die u hebt geconfigureerd:
- Microsoft Entra: clientSecret
- Google: googleClientSecret
- Facebook: facebookAppSecret
- X: twitterConsumerSecret
- Microsoft-account: microsoftAccountClientSecret
Belangrijk

De geheime waarden zijn belangrijke beveiligingsreferenties en moeten zorgvuldig worden afgehandeld. Deel deze waarden niet of persistent op een lokale computer.
Maak instellingen voor sleuf-plaktoepassingen voor elke geheime waarde. U kunt de naam van elke toepassingsinstelling kiezen. De waarde moet overeenkomen met wat u in de vorige stap hebt verkregen of verwijzen naar een Key Vault-geheim dat u met die waarde hebt gemaakt.

Als u de instelling wilt maken, kunt u Azure Portal gebruiken of een variant van het volgende uitvoeren voor elke provider:
```
# For Web Apps, Google example    
az webapp config appsettings set -g <group_name> -n <site_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

# For Azure Functions, X example
az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
```
Notitie

De toepassingsinstellingen voor deze configuratie moeten worden gemarkeerd als sleuf-plakkerig, wat betekent dat ze niet tussen omgevingen worden verplaatst tijdens een sleufwisselingsbewerking. Dit komt doordat uw verificatieconfiguratie zelf is gekoppeld aan de omgeving.
Maak een nieuw JSON-bestand met de naam authsettings.json. Neem de uitvoer die u eerder hebt ontvangen en verwijder elke geheime waarde ervan. Schrijf de resterende uitvoer naar het bestand en zorg ervoor dat er geen geheim is opgenomen. In sommige gevallen kan de configuratie matrices bevatten die lege tekenreeksen bevatten. Zorg ervoor dat dat microsoftAccountOAuthScopes niet het geval is en als dat het geval is, zet u die waarde over op null.

Voeg een eigenschap toe aan authsettings.json die verwijst naar de naam van de toepassingsinstelling die u eerder hebt gemaakt voor elke provider:

Microsoft Entra: clientSecretSettingName
Google: googleClientSecretSettingName
Facebook: facebookAppSecretSettingName
X: twitterConsumerSecretSettingName
Microsoft-account: microsoftAccountClientSecretSettingName

Een voorbeeldbestand na deze bewerking kan er ongeveer als volgt uitzien, in dit geval alleen geconfigureerd voor Microsoft Entra-id:

{
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
    "name": "authsettings",
    "type": "Microsoft.Web/sites/config",
    "location": "Central US",
    "properties": {
        "enabled": true,
        "runtimeVersion": "~1",
        "unauthenticatedClientAction": "AllowAnonymous",
        "tokenStoreEnabled": true,
        "allowedExternalRedirectUrls": null,
        "defaultProvider": "AzureActiveDirectory",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/0b2ef922-672a-4707-9643-9a5726eec524/",
        "allowedAudiences": [
            "https://mywebapp.azurewebsites.net"
        ],
        "additionalLoginParams": null,
        "isAadAutoProvisioned": true,
        "aadClaimsAuthorization": null,
        "googleClientId": null,
        "googleClientSecret": null,
        "googleClientSecretSettingName": null,
        "googleOAuthScopes": null,
        "facebookAppId": null,
        "facebookAppSecret": null,
        "facebookAppSecretSettingName": null,
        "facebookOAuthScopes": null,
        "gitHubClientId": null,
        "gitHubClientSecret": null,
        "gitHubClientSecretSettingName": null,
        "gitHubOAuthScopes": null,
        "twitterConsumerKey": null,
        "twitterConsumerSecret": null,
        "twitterConsumerSecretSettingName": null,
        "microsoftAccountClientId": null,
        "microsoftAccountClientSecret": null,
        "microsoftAccountClientSecretSettingName": null,
        "microsoftAccountOAuthScopes": null,
        "isAuthFromFile": "false"
    }   
}

Verzend dit bestand als de nieuwe verificatie-/autorisatieconfiguratie voor uw app:

az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

Controleer of uw app na deze beweging nog steeds werkt zoals verwacht.
Verwijder het bestand dat in de vorige stappen is gebruikt.

U hebt de app nu gemigreerd om geheimen van id-providers op te slaan als toepassingsinstellingen.

Ondersteuning voor registraties van Microsoft-accountproviders

Als uw bestaande configuratie een Microsoft-accountprovider bevat en geen Microsoft Entra-provider bevat, kunt u de configuratie overschakelen naar de Microsoft Entra-provider en vervolgens de migratie uitvoeren. Dit doet u als volgt:

Ga naar App-registraties in Azure Portal en zoek de registratie die is gekoppeld aan uw Microsoft-accountprovider. Deze bevindt zich mogelijk onder de kop 'Toepassingen van persoonlijk account'.
Ga naar de pagina Verificatie voor de registratie. Onder Omleidings-URI's ziet u een vermelding die eindigt op /.auth/login/microsoftaccount/callback. Kopieer deze URI.
Voeg een nieuwe URI toe die overeenkomt met de URI die u zojuist hebt gekopieerd, behalve dat deze in plaats daarvan eindigt /.auth/login/aad/callback. Hierdoor kan de registratie worden gebruikt door de App Service-verificatie-/autorisatieconfiguratie.
Navigeer naar de App Service-verificatie-/autorisatieconfiguratie voor uw app.
Verzamel de configuratie voor de Microsoft-accountprovider.
Configureer de Microsoft Entra-provider met behulp van de beheermodus Geavanceerd, waarbij u de client-id en clientgeheimwaarden opgeeft die u in de vorige stap hebt verzameld. Gebruik voor de URL <authentication-endpoint>/<tenant-id>/v2.0van de uitgever het verificatie-eindpunt en vervang< het verificatie-eindpunt> door het verificatie-eindpunt voor uw cloudomgeving (bijvoorbeeld 'https://login.microsoftonline.com" voor globale Microsoft Entra-id) vervangt <u ook tenant-id> door uw directory-id (tenant).
Nadat u de configuratie hebt opgeslagen, test u de aanmeldingsstroom door in uw browser naar het /.auth/login/aad eindpunt op uw site te navigeren en de aanmeldingsstroom te voltooien.
Op dit moment hebt u de configuratie gekopieerd, maar blijft de bestaande configuratie van de Microsoft-accountprovider behouden. Voordat u deze verwijdert, moet u ervoor zorgen dat alle onderdelen van uw app verwijzen naar de Microsoft Entra-provider via aanmeldingskoppelingen, enzovoort. Controleer of alle onderdelen van uw app werken zoals verwacht.
Zodra u hebt gevalideerd dat dingen werken met de Microsoft Entra-provider, kunt u de configuratie van de Microsoft-accountprovider verwijderen.

Waarschuwing

Het is mogelijk om de twee registraties te convergeren door de ondersteunde accounttypen voor de registratie van de Microsoft Entra-app te wijzigen. Dit dwingt echter een nieuwe toestemmingsprompt af voor microsoft-accountgebruikers en de identiteitsclaims van die gebruikers kunnen verschillen in structuur, sub met name het wijzigen van waarden omdat er een nieuwe app-id wordt gebruikt. Deze aanpak wordt niet aanbevolen, tenzij dit grondig wordt begrepen. U moet in plaats daarvan wachten op ondersteuning voor de twee registraties in het V2-API-gebied.

Overschakelen naar V2

Zodra de bovenstaande stappen zijn uitgevoerd, gaat u naar de app in Azure Portal. Selecteer de sectie Verificatie (preview).

U kunt ook een PUT-aanvraag indienen voor de config/authsettingsv2 resource onder de siteresource. Het schema voor de nettolading is hetzelfde als vastgelegd in de configuratie op basis van bestanden.

Uw app vastmaken aan een specifieke versie van de verificatieruntime

Wanneer u verificatie/autorisatie inschakelt, wordt platform-middleware opgenomen in uw HTTP-aanvraagpijplijn, zoals beschreven in het functieoverzicht. Deze platform-middleware wordt periodiek bijgewerkt met nieuwe functies en verbeteringen als onderdeel van routineplatformupdates. Standaard wordt uw web- of functie-app uitgevoerd op de nieuwste versie van deze platform-middleware. Deze automatische updates zijn altijd compatibel met eerdere versies. In het zeldzame geval dat deze automatische update echter een runtimeprobleem voor uw web- of functie-app introduceert, kunt u tijdelijk terugkeren naar de vorige middlewareversie. In dit artikel wordt uitgelegd hoe u een app tijdelijk kunt vastmaken aan een specifieke versie van de verificatie-middleware.

Automatische en handmatige versie-updates

U kunt uw app vastmaken aan een specifieke versie van de platform-middleware door een runtimeVersion instelling voor de app in te stellen. Uw app wordt altijd uitgevoerd op de nieuwste versie, tenzij u ervoor kiest deze expliciet vast te maken aan een specifieke versie. Er worden een paar versies tegelijk ondersteund. Als u vastmaken aan een ongeldige versie die niet meer wordt ondersteund, gebruikt uw app in plaats daarvan de nieuwste versie. Als u altijd de nieuwste versie wilt uitvoeren, stelt u in op runtimeVersion ~1.

De huidige runtimeversie weergeven en bijwerken

U kunt de runtimeversie wijzigen die door uw app wordt gebruikt. De nieuwe runtimeversie moet van kracht worden nadat de app opnieuw is opgestart.

De huidige runtimeversie weergeven

U kunt de huidige versie van de middleware voor platformverificatie bekijken met behulp van de Azure CLI of via een van de ingebouwde HTTP-eindpunten van de versie in uw app.

Vanuit de Azure CLI

Bekijk met behulp van de Azure CLI de huidige middlewareversie met de opdracht az webapp auth show .

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

Vervang in deze code door <my_app_name> de naam van uw app. Vervang ook door <my_resource_group> de naam van de resourcegroep voor uw app.

U ziet het runtimeVersion veld in de CLI-uitvoer. Deze lijkt op de volgende voorbeelduitvoer, die voor duidelijkheid is afgekapt:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}

Vanaf het versie-eindpunt

U kunt ook op het eindpunt /.auth/versie van een app drukken om ook de huidige middlewareversie weer te geven waarop de app wordt uitgevoerd. Deze lijkt op de volgende voorbeelduitvoer:

{
"version": "1.3.2"
}

De huidige runtimeversie bijwerken

Met de Azure CLI kunt u de runtimeVersion instelling in de app bijwerken met de opdracht az webapp auth update .

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

Vervang door <my_app_name> de naam van uw app. Vervang ook door <my_resource_group> de naam van de resourcegroep voor uw app. Vervang ook door <version> een geldige versie van de 1.x-runtime of ~1 voor de nieuwste versie. Zie de releaseopmerkingen voor de verschillende runtimeversies om te bepalen aan welke versie moet worden vastgemaakt.

U kunt deze opdracht uitvoeren vanuit De Azure Cloud Shell door deze te kiezen in het voorgaande codevoorbeeld. U kunt de Azure CLI ook lokaal gebruiken om deze opdracht uit te voeren nadat u az login hebt uitgevoerd om u aan te melden.

Volgende stappen

Zelfstudie: gebruikers eind-tot-eind verifiëren en autoriseren

Delen via