De API- en runtimeversies van App Service-verificatie beheren

In dit artikel wordt beschreven hoe u de API- en runtimeversies van de ingebouwde verificatie en autorisatie in App Service aanpast.

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 nadat een paar wijzigingen zijn aangebracht. Met name de geheime configuratie moet worden verplaatst naar instellingen voor sleufgebonden toepassingen. U kunt de geheime configuratie automatisch verplaatsen vanuit de sectie Verificatie van uw app in de portal.

De configuratieversie bijwerken

Waarschuwing

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

De V2-API biedt geen ondersteuning voor het maken of bewerken van een Microsoft-account als een afzonderlijke provider als 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 Een configuratie overschakelen naar een Microsoft Entra-provider voor meer informatie.

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

  1. Ga naar uw app in de portal en selecteer Instellingenverificatie> in het linkerdeelvenster.
  2. Als de app is geconfigureerd met het V1-model, ziet u een knop Upgrade .
  3. Klik op de Upgrade-knop. 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 een toepassing handmatig migreren naar de V2-API als u de eerder beschreven automatische versie niet wilt gebruiken.

Geheimen verplaatsen naar toepassingsinstellingen

Voer deze stappen uit om geheimen van id-providers te verplaatsen naar toepassingsinstellingen.

  1. Haal uw bestaande configuratie op met behulp van de V1-API:

    az webapp auth show -g <group_name> -n <app_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 en bewaar ze niet op een lokale machine.

  2. Maak slot-sticky toepassingsinstellingen 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 Azure 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 de volgende opdracht uitvoeren voor elke provider:

    # For web apps, Google example    
az webapp config appsettings set -g <group_name> -n <app_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 <app_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    Notitie

    De toepassingsinstellingen voor deze configuratie moeten worden gemarkeerd als slot-sticky, wat betekent dat ze niet tussen omgevingen worden verplaatst tijdens een sleufwisselingsbewerking. Deze configuratie is vereist omdat uw verificatieconfiguratie is gekoppeld aan de omgeving.

  3. Maak een nieuw JSON-bestand met de naam authsettings.json. Neem de uitvoer die u eerder hebt ontvangen en verwijder elke geheime waarde ervan. Voeg de resterende uitvoer toe aan het bestand en zorg ervoor dat er geen geheimen zijn opgenomen. In sommige gevallen kan de configuratie arrays met lege tekenreeksen bevatten. Zorg ervoor dat microsoftAccountOAuthScopes dit niet het geval is. Als dit het geval is, wijzigt u de waarde in null.

  4. 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 instellingenbestand 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/aaaabbbb-0000-cccc-1111-dddd2222eeee/",
        "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"
    }   
}

  5. 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/<app_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Controleer of uw app nog steeds werkt zoals verwacht nadat u het bestand hebt verzonden.

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

Een configuratie overschakelen naar een Microsoft Entra-provider

Als uw bestaande configuratie een Microsoft-accountprovider bevat en geen Microsoft Entra-provider bevat, kunt u de configuratie wijzigen in de Microsoft Entra-provider en vervolgens de migratie uitvoeren:

  1. Ga naar app-registraties in Azure Portal en zoek de registratie die is gekoppeld aan uw Microsoft-accountprovider. Het kan zich onder de rubriek Eigendomstoepassingen bevinden.
  2. Ga naar de pagina Verificatie (preview) voor de registratie. Onder Omleidings-URI ziet u een vermelding die eindigt op /.auth/login/microsoftaccount/callback. Kopieer deze URI.
  3. Voeg een nieuwe URI toe die overeenkomt met de URI die u zojuist hebt gekopieerd, maar beëindig deze met /.auth/login/aad/callback. Met deze URI kan de registratie worden gebruikt door de App Service-verificatie-/autorisatieconfiguratie.
  4. Ga naar uw app in de portal. Selecteer Instellingen>Authenticatie.
  5. Verzamel de configuratie voor de Microsoft-accountprovider.
  6. Configureer de Microsoft Entra-provider met behulp van de geavanceerde beheermodus, waarbij u de client-id en clientgeheimwaarden opgeeft die u in de vorige stap hebt verzameld. Voor de URL van de verlener gebruikt u <authentication-endpoint>/<tenant-id>/v2.0. Vervang <authentication-endpoint> door het verificatie-eindpunt voor uw cloudomgeving (bijvoorbeeld 'https://login.microsoftonline.com" voor globale Microsoft Entra-id). Vervang <tenant-id> door uw directory (tenant) ID.
  7. 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.
  8. 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.
  9. Nadat u hebt gecontroleerd of alles werkt 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. Deze configuratie dwingt echter een nieuwe toestemmingsprompt af voor gebruikers van een Microsoft-account en de identiteitsclaims van die gebruikers kunnen verschillen in structuur, sub met name veranderende waarden omdat er een nieuwe app-id wordt gebruikt. We raden deze aanpak niet aan, tenzij u deze grondig begrijpt. U moet in plaats daarvan wachten op ondersteuning voor de twee registraties in het V2-API-gebied.

Overschakelen naar V2

Nadat u de vorige stappen hebt voltooid, gaat u naar de app in Azure Portal. Selecteer de Verificatie (preview) sectie.

U kunt ook een PUT-request indienen voor de config/authsettingsv2 bron onder de sitebron. Het schema voor de payload is hetzelfde als dat in de bestandsgebaseerde configuratie is vastgelegd.

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 deze sectie 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 te configureren. 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 een ongeldige versie vastzet die niet meer wordt ondersteund, gebruikt uw app in dat geval 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 u de app opnieuw hebt 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

Met behulp van de Azure CLI bekijkt u 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 <my_resource_group> door de naam van de resourcegroep voor uw app.

U ziet het runtimeVersion veld in de CLI-uitvoer. Het lijkt op de volgende voorbeelduitvoer, die om de duidelijkheid is ingekort.

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Vanaf het versie-eindpunt

U kunt ook het eindpunt /.auth/version in een app bereiken om de huidige middlewareversie weer te geven waarop de app wordt uitgevoerd. De uitvoer ziet er ongeveer als volgt uit:

{
"version": "1.3.2"
}

De huidige runtimeversie bijwerken

Met Azure CLI kunt u de runtimeVersion instelling in een app bijwerken met behulp van 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 <my_resource_group> door de naam van de resourcegroep voor uw app. Vervang door <version> een geldige versie van de 1.x runtime of gebruiken ~1 voor de nieuwste versie. Zie het overzicht van runtimeversies van Azure Functions om de versie te bepalen waaraan moet worden vastgemaakt voor Azure Functions.

U kunt deze opdracht uitvoeren vanuit De Azure Cloud Shell door Open Cloud Shell te selecteren 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 stap

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

  • Last updated on