Udostępnij za pośrednictwem

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

  • Artykuł

W tym artykule pokazano, jak dostosować interfejs API i wersje ś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 środowisku "Uwierzytelnianie" 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 należy przenieść konfigurację wpisu tajnego do ustawień aplikacji sticky. Można to zrobić automatycznie w sekcji "Uwierzytelnianie" portalu dla aplikacji.

Aktualizacja wersji konfiguracji

Ostrzeżenie

Migracja do wersji 2 spowoduje wyłączenie zarządzania 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 tego cofnąć.

Interfejs API w wersji 2 nie obsługuje tworzenia ani edytowania konta Microsoft jako odrębnego dostawcy, jak to miało miejsce w wersji 1. Zamiast tego używa zbieżnych Platforma tożsamości Microsoft do logowania użytkowników zarówno z kontami Microsoft Entra, jak i osobistymi kontami Microsoft. Podczas przełączania do interfejsu API w wersji 2 konfiguracja microsoft Entra w wersji 1 jest używana do konfigurowania dostawcy Platforma tożsamości Microsoft. Dostawca konta Microsoft w wersji 1 zostanie przeniesiony do procesu migracji i będzie nadal działać normalnie, ale należy przejść do nowszego modelu Platforma tożsamości Microsoft. Aby dowiedzieć się więcej, zobacz Pomoc techniczna dotycząca rejestracji dostawców kont Microsoft.

Zautomatyzowany proces migracji spowoduje przeniesienie wpisów tajnych dostawcy do ustawień aplikacji, a następnie przekonwertowanie pozostałej części konfiguracji na nowy format. Aby użyć automatycznej migracji:

  1. Przejdź do aplikacji w portalu i wybierz opcję menu Uwierzytelnianie .
  2. Jeśli aplikacja jest skonfigurowana przy użyciu modelu w wersji 1, zostanie wyświetlony przycisk Uaktualnij .
  3. Przejrzyj opis w wierszu polecenia 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ć wersji automatycznej wymienionej powyżej.

Przenoszenie wpisów tajnych do ustawień aplikacji

  1. Pobierz istniejącą konfigurację przy użyciu interfejsu API w wersji 1:

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

    W wynikowym ładunku JSON zanotuj wartość wpisu tajnego użytą dla każdego skonfigurowanego dostawcy:

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

    Ważne

    Wartości wpisów tajnych są ważnymi poświadczeniami zabezpieczeń i powinny być starannie obsługiwane. 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 Key Vault utworzonego za pomocą tej wartości.

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

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

    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 zamiany miejsca. Dzieje się tak, 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 niego każdą wartość wpisu tajnego. Zapisz pozostałe dane wyjściowe w pliku, upewniając się, że nie dołączono wpisu tajnego. W niektórych przypadkach konfiguracja może zawierać tablice zawierające puste ciągi. Upewnij się, że microsoftAccountOAuthScopes ta wartość nie jest, a jeśli tak, przełącz ją na null.

  4. Dodaj do tej właściwości nazwę authsettings.json ustawienia aplikacji utworzoną wcześniej dla każdego dostawcy:

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

    Przykładowy plik 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/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. 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/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Sprawdź, czy aplikacja nadal działa zgodnie z oczekiwaniami po tym gestie.

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

Aplikacja została zmigrowana do przechowywania wpisów tajnych dostawcy tożsamości jako ustawień aplikacji.

Obsługa rejestracji dostawców kont Microsoft

Jeśli istniejąca konfiguracja zawiera dostawcę konta Microsoft i nie zawiera dostawcy usługi Microsoft Entra, możesz przełączyć konfigurację do dostawcy Microsoft Entra, a następnie przeprowadzić migrację. Czynność:

  1. Przejdź do Rejestracje aplikacji w witrynie Azure Portal i znajdź rejestrację skojarzona z dostawcą konta Microsoft. Może to być pod nagłówkiem "Aplikacje z konta osobistego".
  2. Przejdź do strony "Uwierzytelnianie", aby uzyskać rejestrację. W obszarze "Identyfikatory 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 tym, który został właśnie skopiowany, z wyjątkiem tego, że ma on koniec w elemecie /.auth/login/aad/callback. Pozwoli to na użycie rejestracji przez konfigurację uwierzytelniania/autoryzacji usługi App Service.
  4. Przejdź do konfiguracji uwierzytelniania/autoryzacji usługi App Service dla aplikacji.
  5. Zbierz konfigurację dostawcy kont Microsoft.
  6. Skonfiguruj dostawcę firmy Microsoft Entra przy użyciu trybu zarządzania "Zaawansowane", podając identyfikator klienta i wartości wpisów tajnych klienta zebranych w poprzednim kroku. W przypadku adresu URL wystawcy użyj <authentication-endpoint>/<tenant-id>/v2.0i zastąp wartość <authentication-endpoint punktem końcowym> uwierzytelniania dla środowiska chmury (np. "https://login.microsoftonline.com" w przypadku globalnego identyfikatora entra firmy Microsoft) należy również zastąpić <identyfikator> dzierżawy 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 ukończ przepływ logowania.
  8. Na tym etapie pomyślnie skopiowano konfigurację, ale istniejąca konfiguracja dostawcy kont Microsoft pozostaje. Przed usunięciem upewnij się, że wszystkie części aplikacji odwołują się do dostawcy Microsoft Entra za pośrednictwem linków logowania itp. Sprawdź, czy wszystkie części aplikacji działają zgodnie z oczekiwaniami.
  9. Po sprawdzeniu, czy elementy działają względem dostawcy Microsoft Entra, możesz usunąć konfigurację dostawcy konta Microsoft.

Ostrzeżenie

Możliwe jest połączenie dwóch rejestracji przez zmodyfikowanie obsługiwanych typów kont dla rejestracji aplikacji Microsoft Entra. Wymusiłoby to jednak nowy monit o wyrażenie zgody dla użytkowników konta Microsoft, a oświadczenia tożsamości tych użytkowników mogą być różne w strukturze, zwłaszcza zmieniając wartości, sub ponieważ jest używany nowy identyfikator aplikacji. Takie podejście nie jest zalecane, chyba że zostanie dokładnie zrozumiane. Zamiast tego należy poczekać na obsługę dwóch rejestracji na powierzchni interfejsu API w wersji 2.

Przełączanie do wersji 2

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

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

Przypinanie aplikacji do określonej wersji środowiska uruchomieniowego uwierzytelniania

Po włączeniu uwierzytelniania/autoryzacji oprogramowanie pośredniczące 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 funkcji będzie działać w najnowszej wersji tego oprogramowania pośredniczącego 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 tym artykule 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, ustawiając runtimeVersion ustawienie dla aplikacji. Aplikacja zawsze działa w najnowszej wersji, chyba że zdecydujesz się jawnie przypiąć ją z powrotem do określonej wersji. Jednocześnie będzie obsługiwanych kilka wersji. Jeśli przypniesz do nieprawidłowej wersji, która nie jest już obsługiwana, aplikacja będzie używać 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

Możesz wyświetlić bieżącą wersję oprogramowania pośredniczącego uwierzytelniania platformy przy użyciu interfejsu wiersza polecenia platformy lub za pośrednictwem jednego z wbudowanych punktów końcowych HTTP wersji w aplikacji.

Z poziomu interfejsu wiersza polecenia platformy Azure

Za pomocą interfejsu wiersza polecenia platformy Azure wyświetl bieżącą wersję oprogramowania pośredniczącego za pomocą 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> ciąg nazwą aplikacji. Zastąp <my_resource_group> również nazwą grupy zasobów aplikacji.

Pole zostanie wyświetlone runtimeVersion w danych wyjściowych interfejsu wiersza polecenia. Będzie on podobny do następujących przykładowych danych wyjściowych, które zostały obcięte w celu uzyskania jasności:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Z punktu końcowego 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ę. Będzie on podobny do następujących przykładowych danych wyjściowych:

{
"version": "1.3.2"
}

Aktualizowanie bieżącej wersji środowiska uruchomieniowego

Za pomocą interfejsu wiersza polecenia platformy Azure możesz zaktualizować runtimeVersion ustawienie w aplikacji za pomocą 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> ciąg nazwą aplikacji. Zastąp <my_resource_group> również nazwą grupy zasobów aplikacji. Zastąp <version> również prawidłową wersją środowiska uruchomieniowego 1.x lub ~1 najnowszą wersją. Zapoznaj się z informacjami o wersji w różnych wersjach środowiska uruchomieniowego, aby ułatwić określenie wersji do przypinania.

To polecenie można uruchomić w usłudze Azure Cloud Shell , wybierając pozycję Wypróbuj w poprzednim przykładzie kodu. Możesz również użyć interfejsu wiersza polecenia platformy Azure lokalnie , aby wykonać to polecenie po wykonaniu polecenia az login w celu zalogowania się.

Następne kroki

Samouczek: kompleksowe uwierzytelnianie i autoryzacja użytkowników