Zarządzaj wersjami API i środowiska uruchomieniowego uwierzytelniania usługi App Service

W tym artykule opisano sposób dostosowywania API i wersji środowiska uruchomieniowego wbudowanego uwierzytelniania i autoryzacji w usłudze App Service.

Istnieją dwie wersje interfejsu API zarządzania na potrzeby uwierzytelniania usługi App Service. Wersja V2 jest wymagana w przypadku środowiska uwierzytelniania w witrynie Azure Portal. Aplikacja korzystająca już z interfejsu API w wersji 1 może przeprowadzić uaktualnienie do wersji 2 po wprowadzeniu kilku zmian. W szczególności, tajną konfigurację należy przenieść do ustawień aplikacji typu slot-sticky. Konfigurację sekretną można automatycznie przenieść z sekcji Uwierzytelnianie aplikacji w portalu.

Aktualizacja wersji konfiguracji

Ostrzeżenie

Migracja do wersji 2 wyłącza zarządzanie funkcją uwierzytelniania/autoryzacji usługi App Service dla aplikacji za pośrednictwem niektórych klientów, takich jak istniejące środowisko w witrynie Azure Portal, interfejsie wiersza polecenia platformy Azure i programie Azure PowerShell. Nie można cofnąć tej migracji.

Interfejs API w wersji 2 nie obsługuje tworzenia ani edytowania konta Microsoft jako odrębnego dostawcy, jak w wersji 1. Zamiast tego używa konwergentnej platformy tożsamości Microsoft do logowania użytkowników zarówno z kontami Microsoft Entra, jak i osobistymi kontami Microsoft. Po przełączeniu się na interfejs API w wersji 2, konfiguracja Microsoft Entra w wersji 1 jest używana do ustawienia dostawcy platformy tożsamości Microsoft. Dostawca kont Microsoft w wersji 1 jest uwzględniany w procesie migracji i nadal działa normalnie, lecz zaleca się przejście do nowszego modelu platformy tożsamości firmy Microsoft. Aby uzyskać więcej informacji, zobacz Przełączanie konfiguracji na dostawcę usługi Microsoft Entra.

Zautomatyzowany proces migracji przenosi sekrety dostawcy do ustawień aplikacji, a następnie konwertuje resztę konfiguracji na nowy format. Aby użyć automatycznej migracji:

  1. Przejdź do aplikacji w portalu i wybierz Ustawienia>Uwierzytelnianie w lewym panelu.
  2. Jeśli aplikacja jest skonfigurowana z modelem w wersji 1, zostanie wyświetlony przycisk Uaktualnij .
  3. Wybierz przycisk Uaktualnij . Przejrzyj opis w oknie dialogowym potwierdzenia. Jeśli wszystko będzie gotowe do przeprowadzenia migracji, wybierz pozycję Uaktualnij w wierszu polecenia.

Ręczne zarządzanie migracją

Poniższe kroki umożliwiają ręczne migrowanie aplikacji do interfejsu API w wersji 2, jeśli nie chcesz używać opisanej wcześniej wersji automatycznej.

Przenoszenie wpisów tajnych do ustawień aplikacji

Aby przenieść sekrety dostawcy usług tożsamości do ustawień aplikacji, wykonaj następujące kroki.

  1. Pobierz swoją istniejącą konfigurację, korzystając z API V1.

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

    W wynikowym ładunku JSON zanotuj wartość tajną używaną dla każdego skonfigurowanego dostawcy.

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

    Ważne

    Wartości tajne są ważnymi danymi uwierzytelniającymi i powinny być starannie traktowane. Nie udostępniaj tych wartości ani nie utrwalaj ich na komputerze lokalnym.

  2. Utwórz ustawienia aplikacji slot-sticky dla każdej wartości wpisu tajnego. Możesz wybrać nazwę każdego ustawienia aplikacji. Jego wartość powinna odpowiadać wartości uzyskanej w poprzednim kroku lub odwołać się do wpisu tajnego usługi Azure Key Vault utworzonego za pomocą tej wartości.

    Aby utworzyć to ustawienie, możesz użyć witryny Azure Portal lub uruchomić odmianę następującego polecenia dla każdego dostawcy:

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

    Uwaga

    Ustawienia aplikacji dla tej konfiguracji powinny być oznaczone jako slot-sticky, co oznacza, że nie będą one przenoszone między środowiskami podczas operacji slot swap. Ta konfiguracja jest wymagana, ponieważ konfiguracja uwierzytelniania jest powiązana ze środowiskiem.

  3. Utwórz nowy plik JSON o nazwie authsettings.json. Weź dane wyjściowe otrzymane wcześniej i usuń z nich każdą wartość tajną. Dodaj pozostałe dane wyjściowe do pliku, upewniając się, że nie uwzględniono żadnych informacji poufnych. W niektórych przypadkach konfiguracja może zawierać tablice zawierające puste ciągi. Upewnij się, że microsoftAccountOAuthScopes nie działa w ten sposób. Jeśli tak, zmień wartość na null.

  4. Dodaj właściwość do authsettings.json, która wskazuje na nazwę ustawienia aplikacji utworzoną wcześniej dla każdego dostawcy:

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

    Plik ustawień po tej operacji może wyglądać podobnie do poniższego, w tym przypadku skonfigurowany tylko dla identyfikatora Entra firmy Microsoft:

    {
    "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. Prześlij ten plik jako nową konfigurację uwierzytelniania/autoryzacji dla aplikacji:

    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. Sprawdź, czy aplikacja nadal działa zgodnie z oczekiwaniami po przesłaniu pliku.

  7. Usuń plik użyty w poprzednich krokach.

Przeniosłeś teraz aplikację, aby przechowywać sekrety dostawcy tożsamości jako ustawienia aplikacji.

Przełącz konfigurację do dostawcy Microsoft Entra

Jeśli istniejąca konfiguracja zawiera dostawcę kont Microsoft i nie zawiera dostawcy usługi Microsoft Entra, możesz zmienić konfigurację dostawcy microsoft Entra, a następnie przeprowadzić migrację:

  1. Przejdź do obszaru Rejestracje aplikacji w witrynie Azure Portal i znajdź rejestrację skojarzona z dostawcą konta Microsoft. Może to być pod nagłówkiem Posiadane aplikacje.
  2. Przejdź do strony Uwierzytelnianie (wersja zapoznawcza) dla rejestracji. Pod Identyfikatorem URI przekierowania powinien zostać wyświetlony wpis kończący się na /.auth/login/microsoftaccount/callback. Skopiuj ten identyfikator URI.
  3. Dodaj nowy identyfikator URI zgodny z właśnie skopiowanym identyfikatorem, ale zakończ go ciągiem /.auth/login/aad/callback. Ten identyfikator URI umożliwia rejestrację używaną przez konfigurację uwierzytelniania/autoryzacji usługi App Service.
  4. Przejdź do aplikacji w portalu. Wybierz Ustawienia>Uwierzytelnianie.
  5. Zbierz konfigurację dostawcy kont Microsoft.
  6. Skonfiguruj dostawcę Microsoft Entra przy użyciu trybu zaawansowanego zarządzania, podając identyfikator klienta oraz tajne wartości klienta, które zebrałeś w poprzednim kroku. W przypadku adresu URL wystawcy użyj <authentication-endpoint>/<tenant-id>/v2.0. Zastąp <authentication-endpoint>punktem końcowym uwierzytelniania dla swojego środowiska chmurowego (na przykład https://login.microsoftonline.com", dla globalnego Microsoft Entra ID). Zastąp <tenant-id> swoim identyfikatorem katalogu (dzierżawy).
  7. Po zapisaniu konfiguracji przetestuj przepływ logowania, przechodząc w przeglądarce do /.auth/login/aad punktu końcowego w witrynie i kończąc przepływ logowania.
  8. Na tym etapie pomyślnie skopiowano konfigurację, ale konfiguracja istniejącego dostawcy kont Microsoft wciąż jest obecna. Przed usunięciem upewnij się, że wszystkie części aplikacji odwołują się do dostawcy Microsoft Entra za pośrednictwem linków logowania itd. Sprawdź, czy wszystkie części aplikacji działają zgodnie z oczekiwaniami.
  9. Po sprawdzeniu, czy wszystko działa z dostawcą microsoft Entra, możesz usunąć konfigurację dostawcy kont Microsoft.

Ostrzeżenie

Można połączyć te dwie rejestracje, modyfikując obsługiwane typy kont dla rejestracji aplikacji Microsoft Entra. Jednak ta konfiguracja wymusiłaby nowy monit zgody dla użytkowników konta Microsoft, a struktura oświadczeń tożsamości tych użytkowników może się różnić, w szczególności mogą zmieniać się wartości, sub ponieważ jest używany nowy identyfikator aplikacji. Nie zalecamy tego podejścia, chyba że dokładnie to zrozumiesz. Zamiast tego należy poczekać na obsługę dwóch rejestracji na powierzchni API V2.

Przełączanie do wersji 2

Po wykonaniu poprzednich kroków przejdź do aplikacji w witrynie Azure Portal. Wybierz sekcję Uwierzytelnianie (wersja zapoznawcza).

Alternatywnie możesz wysłać żądanie PUT względem zasobu config/authsettingsv2 w ramach zasobu witryny. Schemat ładunku jest taki sam jak schemat przechwycony w konfiguracji opartej na plikach.

Przypnij aplikację do określonej wersji środowiska uruchomieniowego uwierzytelniania

Po włączeniu uwierzytelniania/autoryzacji oprogramowanie pośrednie platformy jest wstrzykiwane do potoku żądania HTTP zgodnie z opisem w przeglądzie funkcji . To oprogramowanie pośredniczące platformy jest okresowo aktualizowane przy użyciu nowych funkcji i ulepszeń w ramach rutynowych aktualizacji platformy. Domyślnie aplikacja internetowa lub aplikacja funkcjonalna działa na najnowszej wersji tego oprogramowania pośredniczącego dla platformy. Te aktualizacje automatyczne są zawsze zgodne z poprzednimi wersjami. Jednak w rzadkim przypadku, gdy ta automatyczna aktualizacja wprowadza problem ze środowiskiem uruchomieniowym aplikacji internetowej lub funkcji, można tymczasowo wycofać poprzednią wersję oprogramowania pośredniczącego. W tej sekcji wyjaśniono, jak tymczasowo przypiąć aplikację do określonej wersji oprogramowania pośredniczącego uwierzytelniania.

Automatyczne i ręczne aktualizacje wersji

Aplikację można przypiąć do określonej wersji oprogramowania pośredniczącego platformy, konfigurując runtimeVersion ustawienie dla aplikacji. Aplikacja zawsze działa w najnowszej wersji, chyba że zdecydujesz się jawnie przypiąć ją do określonej wersji. Naraz jest obsługiwanych kilka wersji. Jeśli przypniesz do nieprawidłowej wersji, która nie jest już obsługiwana, aplikacja używa zamiast tego najnowszej wersji. Aby zawsze uruchamiać najnowszą wersję, ustaw wartość runtimeVersion~1.

Wyświetlanie i aktualizowanie bieżącej wersji środowiska uruchomieniowego

Możesz zmienić wersję środowiska uruchomieniowego używaną przez aplikację. Nowa wersja środowiska uruchomieniowego powinna obowiązywać po ponownym uruchomieniu aplikacji.

Wyświetlanie bieżącej wersji środowiska uruchomieniowego

Bieżącą wersję middleware uwierzytelniania platformy można wyświetlić przy użyciu Azure CLI lub za pośrednictwem jednego z wbudowanych punktów końcowych HTTP w aplikacji.

Z poziomu Azure CLI

Za pomocą Azure CLI wyświetl bieżącą wersję middleware przy użyciu polecenia az webapp auth show.

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

W tym kodzie zastąp <my_app_name> nazwą twojej aplikacji. Zastąp <my_resource_group> nazwą grupy zasobów Twojej aplikacji.

W danych wyjściowych interfejsu wiersza polecenia zostanie wyświetlone pole runtimeVersion. Przypomina następujące przykładowe dane wyjściowe, które są obcięte w celu uzyskania jasności:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Z końcowego punktu wersji

Możesz również trafić do punktu końcowego /.auth/version w aplikacji, aby wyświetlić bieżącą wersję oprogramowania pośredniczącego uruchomioną przez aplikację. Dane wyjściowe będą wyglądać podobnie do następujących:

{
"version": "1.3.2"
}

Aktualizowanie bieżącej wersji środowiska uruchomieniowego

Za pomocą Azure CLI możesz zaktualizować ustawienie runtimeVersion w aplikacji, używając polecenia az webapp auth update:

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

Zastąp <my_app_name> nazwą swojej aplikacji. Zastąp <my_resource_group> nazwą grupy zasobów dla Twojej aplikacji. Zastąp <version> prawidłową wersją 1.x runtime lub użyj ~1 dla najnowszej wersji. Aby określić wersję do przypinania do usługi Azure Functions, zobacz Omówienie wersji środowiska uruchomieniowego usługi Azure Functions.

To polecenie można uruchomić w usłudze Azure Cloud Shell , wybierając pozycję Otwórz usługę Cloud Shell w poprzednim przykładzie kodu. Możesz również użyć lokalnie Azure CLI, aby uruchomić to polecenie po uruchomieniu az login, aby się zalogować.

Następny krok

Samouczek: kompleksowe uwierzytelnianie i autoryzacja użytkowników

  • Last updated on