Spravujte rozhraní API a verze modulu runtime pro ověřování služby App Service

Tento článek popisuje, jak přizpůsobit verze rozhraní API a modulu runtime integrovaného ověřování a autorizace ve službě App Service.

Existují dvě verze rozhraní API pro správu pro ověřování pomocí služby App Service. Pro prostředí ověřování na webu Azure Portal se vyžaduje verze V2. Aplikace, která už používá rozhraní API V1, může po provedení několika změn upgradovat na verzi V2. Konkrétně je nutné přesunout konfiguraci tajných kódů do nastavení aplikace typu slot-sticky. Konfiguraci tajných kódů můžete automaticky přesunout z části Ověřování aplikace na portálu.

Aktualizujte verzi konfigurace

Upozornění

Migrace na verzi 2 zakáže správu funkce ověřování a autorizace služby App Service pro vaši aplikaci prostřednictvím některých klientů, jako je například její stávající prostředí na webu Azure Portal, Azure CLI a Azure PowerShellu. Tuto migraci nelze vrátit zpět.

Rozhraní API V2 nepodporuje vytváření ani úpravy účtu Microsoft jako samostatného poskytovatele, jak to dělá verze 1. Místo toho používá konvergovanou platformu Microsoft Identity Platform k přihlašování uživatelů pomocí účtů Microsoft Entra i osobních účtů Microsoft. Při přechodu na rozhraní API V2 se konfigurace V1 Microsoft Entra použije ke konfiguraci zprostředkovatele platformy Microsoft Identity Platform. Poskytovatel účtu Microsoft V1 je během procesu migrace zahrnut a nadále funguje normálně, ale měli byste přejít na novější model Microsoft Identity Platform. Další informace naleznete v tématu Přepnutí konfigurace na poskytovatele Microsoft Entra.

Automatizovaný proces migrace přesune tajné kódy zprostředkovatele do nastavení aplikace a potom převede zbytek konfigurace do nového formátu. Použití automatické migrace:

  1. Přejděte do aplikace na portálu a v levém podokně vyberte Ověřování nastavení>.
  2. Pokud je aplikace nakonfigurovaná s modelem V1, zobrazí se tlačítko Upgradovat .
  3. Vyberte tlačítko Upgradovat. Zkontrolujte popis v potvrzovací výzvě. Pokud jste připraveni provést migraci, vyberte v příkazovém řádku možnost Upgradovat .

Ruční správa migrace

Následující kroky umožňují ručně migrovat aplikaci do rozhraní API V2, pokud nechcete používat automatickou verzi popsanou výše.

Přesun tajných kódů do nastavení aplikace

Pokud chcete přesunout tajné kódy zprostředkovatele identity do nastavení aplikace, proveďte tyto kroky.

  1. Získejte stávající konfiguraci pomocí rozhraní API V1:

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

    Ve výsledné datové části JSON si poznamenejte hodnotu tajného kódu použitou pro každého zprostředkovatele, který jste nakonfigurovali:

    • Microsoft Entra: clientSecret
    • Google: googleClientSecret
    • Facebook: facebookAppSecret
    • X: twitterConsumerSecret
    • Účet Microsoft: microsoftAccountClientSecret

    Důležité

    Hodnoty tajných kódů jsou důležité přihlašovací údaje zabezpečení a měly by se zpracovávat pečlivě. Tyto hodnoty nesdílejte ani je neuchovávejte na místním počítači.

  2. Vytvořte nastavení aplikace typu slot-sticky pro každou hodnotu tajného kódu. Můžete zvolit název každého nastavení aplikace. Jeho hodnota by měla odpovídat tomu, co jste získali v předchozím kroku, nebo odkazovat na tajný klíč služby Azure Key Vault , který jste vytvořili s touto hodnotou.

    K vytvoření nastavení můžete použít Azure Portal nebo spustit variantu následujícího příkazu pro každého zprostředkovatele:

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

    Poznámka:

    Nastavení aplikace pro tuto konfiguraci by se mělo označit jako slot-sticky, což znamená, že se během operace prohození slotu nepřesunou z jednoho prostředí do druhého. Tato konfigurace se vyžaduje, protože konfigurace ověřování je svázaná s prostředím.

  3. Vytvořte nový soubor JSON s názvem authsettings.json. Převezměte výstup, který jste obdrželi dříve, a odeberte z ní každou hodnotu tajného kódu. Přidejte zbývající výstup do souboru a ujistěte se, že nejsou zahrnuté žádné tajné kódy. V některých případech může mít konfigurace pole, která obsahují prázdné řetězce. Ujistěte se, že microsoftAccountOAuthScopes nefunguje. Pokud ano, změňte hodnotu na null.

  4. Přidejte vlastnost authsettings.json , která odkazuje na název nastavení aplikace, který jste vytvořili dříve pro každého zprostředkovatele:

    • Microsoft Entra: clientSecretSettingName
    • Google: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingName
    • X: twitterConsumerSecretSettingName
    • Účet Microsoft: microsoftAccountClientSecretSettingName

    Soubor nastavení po této operaci může vypadat podobně jako následující, v tomto případě je nakonfigurovaný pouze pro 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. Odešlete tento soubor jako novou konfiguraci ověřování/autorizace pro vaši aplikaci:

    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. Po odeslání souboru ověřte, že vaše aplikace stále funguje podle očekávání.

  7. Odstraňte soubor použitý v předchozích krocích.

Teď jste migrovali aplikaci tak, aby ukládaly tajné kódy zprostředkovatele identity jako nastavení aplikace.

Přepnutí konfigurace na poskytovatele Microsoft Entra

Pokud vaše stávající konfigurace obsahuje poskytovatele účtu Microsoft a neobsahuje zprostředkovatele Microsoft Entra, můžete konfiguraci změnit na poskytovatele Microsoft Entra a pak provést migraci:

  1. Na webu Azure Portal přejděte na registrace aplikací a vyhledejte registraci přidruženou k vašemu poskytovateli účtu Microsoft. Může to být pod nadpisem Vlastněné aplikace .
  2. Přejděte na stránku Ověřování (Preview) pro registraci. V části Identifikátor URI přesměrování by se měla zobrazit položka končící na /.auth/login/microsoftaccount/callback. Zkopírujte tento identifikátor URI.
  3. Přidejte nový identifikátor URI, který odpovídá právě zkopírovanému identifikátoru URI, ale ukončete jej /.auth/login/aad/callback. Tento identifikátor URI umožňuje, aby byla registrace využita konfigurací ověřování/autorizace služby App Service.
  4. Přejděte do aplikace na portálu. Vyberte Ověřování nastavení>.
  5. Shromážděte konfiguraci pro poskytovatele účtů Microsoft.
  6. Nakonfigurujte zprostředkovatele Microsoft Entra pomocí režimu rozšířené správy a zadejte ID klienta a hodnoty tajných klíčů klienta, které jste shromáždili v předchozím kroku. Pro adresu URL vystavitele použijte <authentication-endpoint>/<tenant-id>/v2.0. Nahraďte <authentication-endpoint>koncový bod ověřování pro vaše cloudové prostředí (například "https://login.microsoftonline.com" pro globální Microsoft Entra ID). Nahraďte <tenant-id> vaším ID adresáře (tenanta).
  7. Po uložení konfigurace otestujte tok přihlášení tak, že přejdete v prohlížeči na /.auth/login/aad koncový bod na webu a dokončíte tok přihlášení.
  8. V tuto chvíli jste konfiguraci úspěšně zkopírovali, ale stávající konfigurace poskytovatele účtu Microsoft zůstane. Než ho odeberete, ujistěte se, že všechny části vaší aplikace odkazují na poskytovatele Microsoft Entra prostřednictvím přihlašovacích odkazů atd. Ověřte, že všechny části aplikace fungují podle očekávání.
  9. Po ověření, že všechno funguje s poskytovatelem Microsoft Entra, můžete odebrat konfiguraci poskytovatele účtu Microsoft.

Upozornění

Tyto dvě registrace je možné konvergovat úpravou podporovaných typů účtů pro registraci aplikace Microsoft Entra. Tato konfigurace však vynutí novou výzvu k vyjádření souhlasu pro uživatele účtu Microsoft a deklarace identity těchto uživatelů se můžou lišit ve struktuře, zejména při změně hodnot, sub protože se používá nové ID aplikace. Tento přístup nedoporučujeme, pokud ho důkladně nepochopíte. Místo toho byste měli počkat na podporu dvou registrací na ploše rozhraní API V2.

Přepnutí na V2

Po dokončení předchozích kroků přejděte do aplikace na webu Azure Portal. Vyberte část Ověřování (Preview).

Alternativně můžete vytvořit požadavek PUT na config/authsettingsv2 prostředek v rámci prostředku lokality. Schéma datové části je stejné jako schéma zachycené v konfiguraci založené na souborech.

Přiřazení aplikace na konkrétní verzi runtime pro ověřování

Když povolíte ověřování nebo autorizaci, vloží se middleware platformy do kanálu požadavku HTTP, jak je popsáno v přehledu funkce. Tento middleware platformy se pravidelně aktualizuje o nové funkce a vylepšení v rámci rutinních aktualizací platformy. Ve výchozím nastavení běží vaše webová aplikace nebo aplikace funkcí na nejnovější verzi tohoto middlewaru platformy. Tyto automatické aktualizace jsou vždy zpětně kompatibilní. Ve vzácných případech, kdy tato automatická aktualizace způsobí problém s modulem runtime pro váš web nebo aplikaci funkcí, můžete dočasně přejít zpět k předchozí verzi middlewaru. Tato část vysvětluje, jak dočasně připnout aplikaci na konkrétní verzi ověřovacího middlewaru.

Automatické a ruční aktualizace verzí

Aplikaci můžete připnout na konkrétní verzi middlewaru platformy nakonfigurováním nastavení aplikace runtimeVersion. Pokud se nerozhodnete výslovně připnout na konkrétní verzi, vaše aplikace se vždy spouští na nejnovější verzi. Najednou se podporuje několik verzí. Pokud jste připnuli na neplatnou verzi, která už není podporovaná, vaše aplikace místo toho používá nejnovější verzi. Chcete-li vždy používat nejnovější verzi, nastavte runtimeVersion na hodnotu ~1.

Zobrazení a aktualizace aktuální verze modulu runtime

Můžete změnit verzi modulu runtime používanou vaší aplikací. Nová verze modulu runtime by se měla projevit po restartování aplikace.

Zobrazení aktuální verze modulu runtime

Aktuální verzi middlewaru ověřování platformy můžete zobrazit pomocí Azure CLI nebo prostřednictvím některého z předdefinovaných koncových bodů HTTP ve vaší aplikaci.

Pomocí Azure CLI

Pomocí Azure CLI zobrazte aktuální verzi middlewaru pomocí příkazu az webapp auth show .

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

V tomto kódu nahraďte <my_app_name> názvem vaší aplikace. Nahraďte <my_resource_group> názvem skupiny prostředků pro vaši aplikaci.

Pole runtimeVersion se zobrazí ve výstupu CLI. Podobá se následujícímu příkladu výstupu, který je zkrácen pro přehlednost:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Z koncového bodu verze

Můžete také přejít na koncový bod /.auth/version v aplikaci a zobrazit aktuální verzi middlewaru, na které aplikace běží. Výstup bude vypadat nějak takto:

{
"version": "1.3.2"
}

Aktualizace aktuální verze modulu runtime

Pomocí Azure CLI můžete nastavení v aplikaci aktualizovat runtimeVersion pomocí příkazu az webapp auth update :

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

Nahraďte <my_app_name> názvem aplikace. Nahraďte <my_resource_group> názvem skupiny prostředků pro vaši aplikaci. Nahraďte <version> platnou verzí runtime 1.x nebo použijte ~1 pro nejnovější verzi. Pokud chcete zjistit verzi, ke které se má připnout pro Azure Functions, podívejte se na přehled verzí modulu runtime Azure Functions.

Tento příkaz můžete spustit z Azure Cloud Shellu tak, že v předchozí ukázce kódu vyberete Open Cloud Shell . Tento příkaz můžete spustit také místně pomocí Azure CLI po spuštění příkazu az login a přihlásit se.

Další krok

Kurz: Komplexní ověřování a autorizace uživatelů

  • Last updated on