Sdílet prostřednictvím

Správa rozhraní API a verzí modulu runtime ověřování služby App Service

  • Článek

V tomto článku se dozvíte, 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. Můžete to provést automaticky v části Ověřování na portálu pro vaši aplikaci.

Aktualizujte verzi konfigurace

Upozorňující

Migrace na verzi 2 zakáže správu funkce ověřování/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. Nelze to vrátit zpět.

Rozhraní API V2 nepodporuje vytváření ani úpravy účtu Microsoft jako jedinečného poskytovatele, jak bylo provedeno ve verzi 1. Místo toho používá konvergovanou platformu Microsoft Identity Platform k přihlášení uživatelů s účtem Microsoft Entra i osobními účty Microsoft. Při přechodu na rozhraní API V2 se konfigurace V1 Microsoft Entra používá ke konfiguraci zprostředkovatele Microsoft Identity Platform. Poskytovatel účtu Microsoft V1 se přenese do procesu migrace a bude fungovat normálně, ale měli byste přejít na novější model Microsoft Identity Platform. Další informace najdete v tématu Podpora pro registraci zprostředkovatele účtu Microsoft.

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

  1. Přejděte do aplikace na portálu a vyberte možnost Nabídky Ověřování .
  2. Pokud je aplikace nakonfigurovaná pomocí modelu V1, zobrazí se tlačítko Upgradovat .
  3. 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 vám umožní ručně migrovat aplikaci do rozhraní API V2, pokud nechcete používat automatickou verzi uvedenou výše.

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

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

    az webapp auth show -g <group_name> -n <site_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áváte 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 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ích možností pro každého zprostředkovatele:

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

    Poznámka:

    Nastavení aplikace pro tuto konfiguraci by mělo být označeno jako slot-sticky, což znamená, že se během operace prohození slotu nepřesunou mezi prostředími. Důvodem je to, že samotná 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. Zapište zbývající výstup do souboru a ujistěte se, že není zahrnutý žádný tajný kód. V některých případech může mít konfigurace pole obsahující prázdné řetězce. Ujistěte se, že microsoftAccountOAuthScopes ne, a pokud ano, přepněte tuto 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

    Příklad souboru po této operaci může vypadat podobně jako v tomto případě pouze pro 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. 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/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Po tomto gestu 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.

Podpora registrací zprostředkovatele účtu Microsoft

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

  1. Přejděte na Registrace aplikací na webu Azure Portal a vyhledejte registraci přidruženou k vašemu poskytovateli účtu Microsoft. Může být pod nadpisem Aplikace z osobního účtu.
  2. Přejděte na stránku Ověřování pro registraci. V části Identifikátory 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ým identifikátoru, s výjimkou toho, že končí ./.auth/login/aad/callback To umožní registraci používat konfiguraci ověřování nebo autorizace služby App Service.
  4. Přejděte do konfigurace ověřování nebo autorizace služby App Service pro vaši aplikaci.
  5. Shromážděte konfiguraci pro poskytovatele účtu 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.0a nahraďte <koncový bod> ověřování koncovým bodem ověřování pro vaše cloudové prostředí (např. ";https://login.microsoftonline.com" pro globální ID Microsoft Entra) nahraďte <také ID> tenanta id vašeho 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 vašem webu a dokončíte tok přihlášení.
  8. V tomto okamžiku 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. Jakmile ověříte, že věci fungují s poskytovatelem Microsoft Entra, můžete odebrat konfiguraci poskytovatele účtu Microsoft.

Upozorňující

Tyto dvě registrace je možné sloučit úpravou podporovaných typů účtů pro registraci aplikace Microsoft Entra. To by však vynutilo 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, sub a to zejména při změně hodnot, protože se používá nové ID aplikace. Tento přístup se nedoporučuje, pokud není důkladně srozumitelný. Místo toho byste měli počkat na podporu dvou registrací na ploše rozhraní API V2.

Přepnutí na V2

Po provedení výše uvedených kroků přejděte na webu Azure Portal do aplikace. 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 zachycené v konfiguraci založené na souborech.

Připnutí aplikace na konkrétní verzi modulu runtime 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í se vaše webová aplikace nebo aplikace funkcí spustí na nejnovější verzi tohoto middlewaru platformy. Tyto automatické aktualizace jsou vždy zpětně kompatibilní. Ve výjimečných událostech, kdy tato automatická aktualizace zavádí problém s modulem runtime pro web nebo aplikaci funkcí, můžete se dočasně vrátit k předchozí verzi middlewaru. Tento článek 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 nastavením runtimeVersion nastavení aplikace. Pokud se nerozhodnete, že ji explicitně připnete zpět na konkrétní verzi, vaše aplikace se vždy spustí na nejnovější verzi. Najednou bude podporováno několik verzí. Pokud se připnete na neplatnou verzi, která už není podporovaná, bude vaše aplikace místo toho používat nejnovější verzi. Pokud chcete vždy spustit nejnovější verzi, nastavte runtimeVersion na ~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 buď pomocí Azure CLI, nebo prostřednictvím některého z integrovaných koncových bodů HTTP ve vaší aplikaci.

Z 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> také názvem skupiny prostředků pro vaši aplikaci.

Pole se zobrazí runtimeVersion ve výstupu rozhraní příkazového řádku. Bude vypadat podobně jako v následujícím příkladu výstupu, který byl 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é je aplikace spuštěná. Bude vypadat podobně jako v následujícím příkladu výstupu:

{
"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> také názvem skupiny prostředků pro vaši aplikaci. Nahraďte <version> také platnou verzí modulu runtime 1.x nebo ~1 pro nejnovější verzi. Přečtěte si poznámky k verzi různých verzí modulu runtime, které vám pomůžou určit verzi, na které se má připnout.

Tento příkaz můžete spustit z Azure Cloud Shellu tak, že v předchozí ukázce kódu zvolíte Vyzkoušet. 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ší kroky

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