Hantera API- och körningsversionerna av App Service-autentisering

  • Artikel

Den här artikeln visar hur du anpassar API- och körningsversionerna av den inbyggda autentiseringen och auktoriseringen i App Service.

Det finns två versioner av hanterings-API:et för App Service-autentisering. V2-versionen krävs för autentiseringsupplevelsen i Azure-portalen. En app som redan använder V1-API:et kan uppgradera till V2-versionen när några ändringar har gjorts. Mer specifikt måste den hemliga konfigurationen flyttas till programinställningar med fast plats. Detta kan göras automatiskt från avsnittet "Autentisering" i portalen för din app.

Uppdatera konfigurationsversionen

Varning

Migrering till V2 inaktiverar hanteringen av apptjänstens autentiserings-/auktoriseringsfunktion för ditt program via vissa klienter, till exempel dess befintliga upplevelse i Azure-portalen, Azure CLI och Azure PowerShell. Detta kan inte ångras.

V2-API:et stöder inte skapande eller redigering av Microsoft-konto som en distinkt provider som gjordes i V1. I stället använder den den konvergerade Microsoft platforma za identitete för att logga in användare med både Microsoft Entra och personliga Microsoft-konton. När du växlar till V2-API:et används V1 Microsoft Entra-konfigurationen för att konfigurera Microsoft platforma za identitete-providern. V1 Microsoft-kontoprovidern överförs i migreringsprocessen och fortsätter att fungera som vanligt, men du bör gå över till den nyare Microsoft platforma za identitete modellen. Mer information finns i Support för registreringar av Microsoft-kontoprovider.

Den automatiserade migreringsprocessen flyttar providerhemligheter till programinställningar och konverterar sedan resten av konfigurationen till det nya formatet. Så här använder du den automatiska migreringen:

  1. Gå till din app i portalen och välj menyalternativet Autentisering .
  2. Om appen har konfigurerats med V1-modellen visas en uppgraderingsknapp .
  3. Granska beskrivningen i bekräftelseprompten. Om du är redo att utföra migreringen väljer du Uppgradera i prompten.

Hantera migreringen manuellt

Med följande steg kan du migrera programmet manuellt till V2-API:et om du inte vill använda den automatiska versionen som nämns ovan.

Flytta hemligheter till programinställningar

  1. Hämta din befintliga konfiguration med hjälp av V1-API:et:

    az webapp auth show -g <group_name> -n <site_name>

    Anteckna det hemliga värde som används för varje provider som du har konfigurerat i den resulterande JSON-nyttolasten:

    • Microsoft Entra: clientSecret
    • Google: googleClientSecret
    • Facebook: facebookAppSecret
    • X: twitterConsumerSecret
    • Microsoft-konto: microsoftAccountClientSecret

    Viktigt!

    De hemliga värdena är viktiga säkerhetsautentiseringsuppgifter och bör hanteras noggrant. Dela inte dessa värden eller spara dem på en lokal dator.

  2. Skapa inställningar för slot-sticky-program för varje hemligt värde. Du kan välja namnet på varje programinställning. Värdet ska matcha det du fick i föregående steg eller referera till en Key Vault-hemlighet som du har skapat med det värdet.

    Om du vill skapa inställningen kan du använda Azure-portalen eller köra en variant av följande för varje 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>

    Kommentar

    Programinställningarna för den här konfigurationen ska markeras som slot-sticky, vilket innebär att de inte flyttas mellan miljöer under en växlingsåtgärd. Det beror på att själva autentiseringskonfigurationen är kopplad till miljön.

  3. Skapa en ny JSON-fil med namnet authsettings.json. Ta utdata som du fick tidigare och ta bort varje hemligt värde från det. Skriv återstående utdata till filen och se till att ingen hemlighet ingår. I vissa fall kan konfigurationen ha matriser som innehåller tomma strängar. Kontrollera att microsoftAccountOAuthScopes det inte gör det, och om det gör det växlar du det värdet till null.

  4. Lägg till en egenskap som authsettings.json pekar på namnet på programinställningen som du skapade tidigare för varje provider:

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

    En exempelfil efter den här åtgärden kan se ut ungefär så här, i det här fallet endast konfigurerad för Microsoft Entra-ID:

    {
    "id": "/subscriptions/00d563f8-5b89-4c6a-bcec-c1b9f6d607e0/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"
    }   
}

  5. Skicka den här filen som den nya autentiserings-/auktoriseringskonfigurationen för din 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

  6. Kontrollera att appen fortfarande fungerar som förväntat efter den här gesten.

  7. Ta bort filen som användes i föregående steg.

Nu har du migrerat appen för att lagra identitetsproviderns hemligheter som programinställningar.

Stöd för registreringar av Microsoft-kontoprovider

Om din befintliga konfiguration innehåller en Microsoft-kontoprovider och inte innehåller någon Microsoft Entra-provider kan du växla över konfigurationen till Microsoft Entra-providern och sedan utföra migreringen. Så här gör du:

  1. Gå till Appregistreringar i Azure-portalen och leta reda på registreringen som är associerad med din Microsoft-kontoleverantör. Det kan vara under rubriken "Program från personligt konto".
  2. Gå till sidan "Autentisering" för registreringen. Under "Omdirigerings-URI:er" bör du se en post som slutar på /.auth/login/microsoftaccount/callback. Kopiera den här URI:n.
  3. Lägg till en ny URI som matchar den som du precis kopierade, förutom att den i stället slutar på /.auth/login/aad/callback. Detta gör att registreringen kan användas av App Service-autentiserings-/auktoriseringskonfigurationen.
  4. Navigera till App Service-autentiseringen/auktoriseringskonfigurationen för din app.
  5. Samla in konfigurationen för Microsoft-kontoprovidern.
  6. Konfigurera Microsoft Entra-providern med hanteringsläget "Avancerat" och ange de klient-ID och de klienthemlighetsvärden som du samlade in i föregående steg. För utfärdarens URL använder du <authentication-endpoint>/<tenant-id>/v2.0och ersätter< authentication-endpoint> med autentiseringsslutpunkten för din molnmiljö (t.ex. "https://login.microsoftonline.com" för globalt Microsoft Entra-ID), och ersätter <även klient-ID> med ditt katalog-ID (klientorganisation).
  7. När du har sparat konfigurationen testar du inloggningsflödet genom att navigera i webbläsaren till /.auth/login/aad slutpunkten på webbplatsen och slutföra inloggningsflödet.
  8. Nu har du kopierat konfigurationen över, men den befintliga konfigurationen för Microsoft-kontoprovidern finns kvar. Innan du tar bort den kontrollerar du att alla delar av din app refererar till Microsoft Entra-providern via inloggningslänkar osv. Kontrollera att alla delar av appen fungerar som förväntat.
  9. När du har verifierat att saker fungerar mot Microsoft Entra-providern kan du ta bort konfigurationen för Microsoft-kontoprovidern.

Varning

Det går att konvergera de två registreringarna genom att ändra de kontotyper som stöds för Microsoft Entra-appregistreringen. Detta skulle dock tvinga fram en ny begäran om medgivande för Microsoft-kontoanvändare, och dessa användares identitetsanspråk kan vara olika i strukturen, sub särskilt ändrade värden eftersom ett nytt app-ID används. Den här metoden rekommenderas inte om du inte förstår det noggrant. Du bör i stället vänta på stöd för de två registreringarna på V2 API-ytan.

Växla till V2

När ovanstående steg har utförts navigerar du till appen i Azure-portalen. Välj avsnittet "Autentisering (förhandsversion)".

Du kan också göra en PUT-begäran mot resursen config/authsettingsv2 under platsresursen. Schemat för nyttolasten är detsamma som i filbaserad konfiguration.

Fäst din app på en specifik autentiseringskörningsversion

När du aktiverar autentisering/auktorisering matas plattformsmellanprogram in i din HTTP-begärandepipeline enligt beskrivningen i funktionsöversikten. Det här plattformsmellanprogrammet uppdateras regelbundet med nya funktioner och förbättringar som en del av rutinmässiga plattformsuppdateringar. Som standard körs webb- eller funktionsappen på den senaste versionen av plattformens mellanprogram. Dessa automatiska uppdateringar är alltid bakåtkompatibla. Men om den här automatiska uppdateringen introducerar ett körningsproblem för webb- eller funktionsappen kan du tillfälligt återställa till den tidigare mellanprogramsversionen. Den här artikeln beskriver hur du tillfälligt fäster en app på en viss version av mellanprogrammet för autentisering.

Automatiska och manuella versionsuppdateringar

Du kan fästa appen på en specifik version av plattformsmellanprogrammet genom att ange en runtimeVersion inställning för appen. Appen körs alltid på den senaste versionen om du inte uttryckligen väljer att fästa den i en viss version. Det kommer att finnas några versioner som stöds åt gången. Om du fäster på en ogiltig version som inte längre stöds använder appen den senaste versionen i stället. Om du alltid vill köra den senaste versionen anger du runtimeVersion ~1.

Visa och uppdatera den aktuella körningsversionen

Du kan ändra körningsversionen som används av din app. Den nya körningsversionen bör börja gälla när appen har startats om.

Visa den aktuella körningsversionen

Du kan visa den aktuella versionen av mellanprogrammet för plattformsautentisering antingen med hjälp av Azure CLI eller via någon av de inbyggda HTTP-slutpunkterna i din app.

Från Azure CLI

Använd Azure CLI och visa den aktuella mellanprogramsversionen med kommandot az webapp auth show .

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

I den här koden ersätter du <my_app_name> med namnet på din app. Ersätt <my_resource_group> även med namnet på resursgruppen för din app.

Du ser fältet runtimeVersion i CLI-utdata. Det liknar följande exempelutdata, som har trunkerats för tydlighetens skull:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Från versionsslutpunkten

Du kan också trycka på slutpunkten /.auth/version i en app för att visa den aktuella mellanprogramversionen som appen körs på. Det liknar följande exempelutdata:

{
"version": "1.3.2"
}

Uppdatera den aktuella körningsversionen

Med Azure CLI kan du uppdatera runtimeVersion inställningen i appen med kommandot az webapp auth update .

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

Ersätt <my_app_name> med namnet på din app. Ersätt <my_resource_group> även med namnet på resursgruppen för din app. Ersätt <version> också med en giltig version av 1.x-körningen eller ~1 för den senaste versionen. Se viktig information om de olika körningsversionerna för att fastställa vilken version som ska fästas på.

Du kan köra det här kommandot från Azure Cloud Shell genom att välja Prova i föregående kodexempel. Du kan också använda Azure CLI lokalt för att köra det här kommandot efter att ha kört az login för att logga in.

Nästa steg

Självstudie: Autentisera och auktorisera användare från slutpunkt till slutpunkt