管理 App Service 驗證的 API 和執行階段版本

  • 發行項

針對內建的 App Service 中的驗證和授權，本文說明如何自訂其 API 和執行階段版本。

App Service 驗證的管理 API 有兩個版本。 Azure 入口網站中的「驗證」體驗需要 V2 版本。 已使用 V1 API 的應用程式稍微變更，即可升級至 V2 版本。 具體而言，祕密組態必須移至位置固定的應用程式設定。 從入口網站的 [驗證] 區段中，可以自動為您的應用程式這樣做。

更新組態版本

警告

移轉至 V2 會使得某些用戶端無法管理應用程式的 App Service 驗證/授權功能，例如在 Azure 入口網站、Azure CLI 和 Azure PowerShell 中的現有體驗。 這是不可逆轉的決定。

與 V1 不同，V2 API 不支援建立或編輯 Microsoft 帳戶成為獨特提供者。 相反地，它使用聚合式 Microsoft 身分識別平台，讓使用者以 Microsoft Entra ID 和個人 Microsoft 帳戶登入。 如果切換至 V2 API，則會使用 V1 Microsoft Entra 組態來設定 Microsoft 身分識別平台提供者。 V1 Microsoft 帳戶提供者會隨著移轉流程一起遷移，且繼續正常運作，但您應該改用較新的 Microsoft 身分識別平台模型。 若要深入了解，請參閱支援 Microsoft 帳戶提供者註冊。

自動化移轉流程將提供者祕密移至應用程式設定，然後將組態剩餘部分轉換成新的格式。 使用自動移轉：

  1. 在入口網站中巡覽至您的應用程式，然後選取 [驗證] 功能表選項。
  2. 如果是使用 V1 模型設定應用程式，您會看到 [升級] 按鈕。
  3. 檢閱確認提示中的描述。 如果準備好執行移轉，請在提示中選取 [升級]。

手動管理移轉

如果您不想使用上述的自動做法，下列步驟可讓您手動將應用程式遷移至 V2 API。

將秘密移至應用程式設定

  1. 使用 V1 API 取得現有的設定：

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

    在產生的 JSON 承載中，記下您設定的每個提供者所使用的秘密值：

    • Microsoft Entra ID：clientSecret
    • Google：googleClientSecret
    • Facebook：facebookAppSecret
    • Twitter：twitterConsumerSecret
    • Microsoft 帳戶：microsoftAccountClientSecret

    重要

    秘密值是重要的安全性認證，應該謹慎處理。 請勿分享這些值，也不要保存在本機電腦上。

  2. 為每個秘密值建立位置固定的應用程式設定。 您可以選擇每個應用程式設定的名稱。 其值應該符合您在上一個步驟中取得的值，或參考 Key Vault 秘密 (您使用該值建立)。

    若要建立設定，您可以使用 Azure 入口網站，或執行以下隨著每個提供者而不同的命令：

    # 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, Twitter example
az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    注意

    此組態的應用程式設定應該標示為位置固定，表示在位置交換作業期間不會在環境之間移動。 這是因為驗證設定本身與環境密切相關。

  3. 建立名為 authsettings.json 的新 JSON 檔案。 取得您先前收到的輸出，從中移除每個秘密值。 將剩餘輸出寫入檔案，並確定不含任何秘密。 在某些情況下，設定可能有包含空字串的陣列。 請確定 microsoftAccountOAuthScopes 無此情形，否則，請將該值改為 null。

  4. 在 authsettings.json 中新增屬性，指向您稍早為每個提供者建立的應用程式設定名稱：

    • Microsoft Entra ID：clientSecretSettingName
    • Google：googleClientSecretSettingName
    • Facebook：facebookAppSecretSettingName
    • Twitter：twitterConsumerSecretSettingName
    • Microsoft 帳戶：microsoftAccountClientSecretSettingName

    完成此作業之後的範例檔案可能類似如下，此案例中僅針對 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": "3197c8ed-2470-480a-8fae-58c25558ac9b",
        "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. 提交此檔案給應用程式作為新的驗證/授權設定：

    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. 驗證應用程式在此動作之後仍如預期般運作。

  7. 刪除先前步驟中使用的檔案。

現在應用程式已移轉為將識別提供者祕密儲存為應用程式設定。

支援 Microsoft 帳戶提供者註冊

如果您現有的設定包含 Microsoft 帳戶提供者，但不包含 Microsoft Entra 提供者，您可以將設定切換至 Microsoft Entra 提供者，然後執行移轉。 若要這樣做：

  1. 移至 Azure 入口網站中的應用程式註冊，找出與您的 Microsoft 帳戶提供者相關聯的註冊。 可能位於 [個人帳戶中的應用程式] 標題下。
  2. 巡覽至註冊的 [驗證] 頁面。 在 [重新導向 URI] 下，您應該會看到以 /.auth/login/microsoftaccount/callback 結尾的項目。 複製此 URI。
  3. 新增 URI，與剛複製的 URI 相符，但結尾改成 /.auth/login/aad/callback。 這樣可讓 App Service 驗證/授權設定使用註冊。
  4. 巡覽至應用程式的 App Service 驗證/授權設定。
  5. 收集 Microsoft 帳戶提供者的設定。
  6. 使用「進階」管理模式設定 Microsoft Entra 提供者，並提供您在上一個步驟中收集的用戶端識別碼和用戶端密碼值。 在 [簽發者 URL] 中，使用 <authentication-endpoint>/<tenant-id>/v2.0，並將 <authentication-endpoint> 換成您的雲端環境的驗證端點 (例如，全球 Azure 的 "https://login.microsoftonline.com")，也將 <tenant-id> 換成您的目錄 (租用戶) 識別碼。
  7. 儲存設定之後，在瀏覽器中巡覽至網站上的 /.auth/login/aad 端點，以測試登入流程，並完成登入流程。
  8. 此時，您已成功複製設定，但現有的 Microsoft 帳戶提供者設定仍在。 移除它之前，請確定應用程式的所有部分都透過登入連結等參考 Microsoft Entra 提供者。確認應用程式的所有部分都如預期般運作。
  9. 一旦確認 Microsoft Entra 提供者正常運作，就可以移除 Microsoft 帳戶提供者設定。

警告

修改 Microsoft Entra 應用程式註冊支援的帳戶類型，有可能匯聚兩個註冊。 不過，這會強制 Microsoft 帳戶使用者接受新的同意提示，而這些使用者的身分識別宣告在結構上可能不同，由於使用新的應用程式識別碼，sub 的值明顯不一樣。 除非徹底了解，否則不建議使用此方法。 反而應該在 V2 API 介面中等候支援兩個註冊。

切換至 V2

執行上述步驟之後，巡覽至 Azure 入口網站中的應用程式。 選取 [驗證 (預覽)] 區段。

或者，您可以對網站資源下的 config/authsettingsv2 資源提出 PUT 要求。 承載的架構同於檔案型設定中擷取的架構。

將應用程式鎖定在特定的驗證執行階段版本

啟用驗證/授權時，平台中介軟體會插入 HTTP 要求管線中，如功能概觀所述。 隨著例行性平台更新，此平台中介軟體會定期更新功能並改善。 Web 或函數應用程式預設在此平台中介軟體的最新版本上執行。 這些自動更新一律回溯相容。 在罕見情況下，此自動更新會給 Web 或函數應用程式帶來執行階段問題，但您可以暫時復原到前一個中介軟體版本。 本文說明如何將應用程式暫時鎖定在特定版本的驗證中介軟體。

自動和手動版本更新

您可以設定應用程式的 runtimeVersion 設定，將應用程式鎖定在特定版本的平台中介軟體。 除非您選擇明確鎖回在特定版本，否則應用程式一律在最新版本上執行。 每次都支援幾個版本。 如果您鎖定在已不支援的無效版本，則應用程式會改用最新版本。 若要一律執行最新版本，請將 runtimeVersion 設定為 ~1。

檢視並更新目前的執行階段版本

您可以變更應用程式所使用的執行階段版本。 重新啟動應用程式之後，新的執行階段版本就會生效。

檢視目前的執行階段版本

您可以使用 Azure CLI，或透過應用程式中的其中一個內建版本 HTTP 端點，以檢視平台驗證中介軟體的目前版本。

從 Azure CLI

在 Azure CLI 中，使用 az webapp auth show 命令來檢視目前的中介軟體版本。

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

在此程式碼中，將 <my_app_name> 換成您的應用程式名稱。 也將 <my_resource_group> 換成您的應用程式的資源群組名稱。

您在 CLI 輸出中會看到 runtimeVersion 欄位。 類似下列範例輸出，為求簡潔已截斷：

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
從版本端點

您也可以在應用程式上點閱 /.auth/version 端點，以檢視目前執行應用程式的中介軟體版本。 類似下列範例輸出：

{
"version": "1.3.2"
}

更新目前的執行階段版本

在 Azure CLI 中，您可以使用 az webapp auth update 命令來更新應用程式中的 runtimeVersion 設定。

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

將 <my_app_name> 換成您的應用程式名稱。 也將 <my_resource_group> 換成您的應用程式的資源群組名稱。 還有，將 <version> 換成 1.x 執行階段的有效版本，或換成 ~1 代表最新版本。 請參閱不同執行階段版本的版本資訊，以協助決定要鎖定的版本。

您可以選擇上述程式碼範例中的 [試試看]，從 Azure Cloud Shell 執行此命令。 在執行 az login 登入之後，您也可以使用本機 Azure CLI 來執行此命令。

下一步

教學課程：端對端驗證和授權使用者