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

Den här artikeln beskriver 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. Hemlig konfiguration måste specifikt flyttas till slot-sticky programinställningar. Du kan flytta hemlig konfiguration automatiskt från avsnittet Autentisering i din app på portalen.

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. Den här migreringen kan inte ångras.

V2-API:et stöder inte skapande eller redigering av ett Microsoft-konto som en distinkt provider som V1 gör. I stället använder den den konvergerade Microsoft-identitetsplattformen 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 Microsofts identitetsplattformsprovider. V1 Microsoft-kontoprovidern förs vidare i migreringsprocessen och fortsätter att fungera som vanligt, men du bör gå över till den nyare Microsoft-identitetsplattformsmodellen. Mer information finns i Växla en konfiguration till en Microsoft Entra-provider.

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

  1. Gå till din app i portalen och välj Inställningar>Autentisering i den vänstra rutan.
  2. Om appen har konfigurerats med V1-modellen visas en uppgraderingsknapp .
  3. Välj knappen Uppgradera. 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 ett program manuellt till V2-API:et om du inte vill använda den automatiska version som beskrevs tidigare.

Flytta hemligheter till programinställningar

Slutför de här stegen om du vill flytta identitetsproviderns 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 <app_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 slot-sticky-applikationsinställningar 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 Azure 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 kommando för varje 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>

    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 slot-swapoperation. Den här konfigurationen krävs eftersom 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. Lägg till återstående utdata i filen och se till att inga hemligheter ingår. I vissa fall kan konfigurationen ha matriser som innehåller tomma strängar. Se till att microsoftAccountOAuthScopes inte gör det. Om det gör det ändrar du värdet till null.

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

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

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

  6. Kontrollera att appen fortfarande fungerar som förväntat när du har skickat filen.

  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.

Växla en konfiguration till en Microsoft Entra-provider

Om din befintliga konfiguration innehåller en Microsoft-kontoprovider och inte innehåller någon Microsoft Entra-provider kan du ändra konfigurationen till Microsoft Entra-providern och sedan utföra migreringen:

  1. Gå till Appregistreringar i Azure-portalen och leta reda på registreringen som är associerad med din Microsoft-kontoleverantör. Det kan finnas under rubriken Ägda program .
  2. Gå till sidan Autentisering (förhandsversion) för registreringen. Under Omdirigerings-URI 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, men avsluta den med /.auth/login/aad/callback. Med den här URI:n kan registreringen användas av App Service-autentiserings-/auktoriseringskonfigurationen.
  4. Gå till din app i portalen. Välj Inställningar>Autentisering.
  5. Samla in konfigurationen för Microsoft-kontoleverantören.
  6. Konfigurera Microsoft Entra-providern med hjälp av avancerat hanteringsläge och ange de klient-ID och klienthemlighetsvärden som du samlade in i föregående steg. För utfärdarens URL använder du <authentication-endpoint>/<tenant-id>/v2.0. Ersätt <authentication-endpoint> med autentiseringsslutpunkten för din molnmiljö (till exempel "https://login.microsoftonline.com" för globalt Microsoft Entra-ID). Ersätt <tenant-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 och så vidare. Kontrollera att alla delar av appen fungerar som förväntat.
  9. När du har verifierat att allt fungerar med 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. Den här konfigurationen skulle dock tvinga Microsoft-kontoanvändare att ge sitt samtycke på nytt, och dessa användares identitetsanspråk kan vara olika i sin struktur, sub särskilt förändrade värden på grund av att ett nytt app-ID används. Vi rekommenderar inte den här metoden om du inte förstår den noggrant. Du bör i stället vänta på stöd för de två registreringarna i V2 API-gränssnittet.

Växla till V2

När du har slutfört föregående steg går 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 det som samlas in i filbaserad konfiguration.

Lås din app till en specifik autentiseringsversion av körmiljön

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 det här plattformsmellanprogrammet. 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. I det här avsnittet beskrivs 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 konfigurera 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 på en viss version. Det finns 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 till ~1.

Visa och uppdatera den aktuella körningsversionen

Du kan ändra runtime-versionen som används av din app. Den nya körningsversionen ska träda i kraft när du har startat om appen.

Visa den aktuella körningstidsversionen

Du kan visa den aktuella versionen av plattformsautentiseringens mellanprogram med hjälp av Azure CLI eller via en av de inbyggda VERSION HTTP-slutpunkterna i din app.

Från Azure CLI

Genom att använda Azure CLI visar du 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> med namnet på resursgruppen för din app.

Du ser fältet runtimeVersion i CLI-utdata. Det liknar följande exempelutdata, som trunkeras 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å. Utdata ser ut ungefär så här:

{
"version": "1.3.2"
}

Uppdatera den aktuella runtime-versionen

Med Azure CLI kan du uppdatera runtimeVersion inställningen i en app med hjälp av 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> med namnet på resursgruppen för din app. Ersätt <version> med en giltig version av 1.x runtime, eller använd ~1 för den senaste versionen. Information om vilken version som ska fästas på för Azure Functions finns i Översikt över Azure Functions-körningsversioner.

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

Nästa steg

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

  • Last updated on