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

本文說明如何自訂 App Service 內建認證與授權的 API 與執行版本。

App Service 驗證的管理 API 有兩個版本。 V2 版本是 Azure 入口網站驗證體驗的必要條件。 已經使用 V1 API 的應用程式，經過幾項調整後即可升級到 V2 版本。 具體而言，祕密組態必須移至位置固定的應用程式設定。 你可以從入口網站上應用程式的 認證 區塊自動移動機密設定。

更新組態版本

警告

遷移到 V2 會禁用透過某些客戶端（例如 Azure 入口網站、Azure CLI 和 Azure PowerShell）管理應用程式的 App Service 認證/授權功能的預設體驗。 這種遷移無法逆轉。

V2 API 不支援像 V1 那樣建立或編輯 Microsoft 帳號作為獨立提供者。 相反地，它使用融合的 Microsoft 身份平台 ，讓使用者同時以 Microsoft Entra 和個人 Microsoft 帳號登入。 當您切換至 V2 API 時，會使用 V1 Microsoft Entra 設定來設定 Microsoft 身分識別平台提供者。 V1 Microsoft 帳號提供者在遷移過程中會保留，並繼續正常運作，但你應該轉用更新的 Microsoft 身份平台模型。 欲了解更多資訊，請參閱 「將設定切換至Microsoft Entra提供者」。

自動化遷移程序會將提供者秘密移入應用程式設定，然後將其餘配置轉換成新格式。 若要使用自動遷移：

  1. 進入入口網站的應用程式，在左側選選 「設定>認證 」。
  2. 如果應用程式設定為 V1 型號，你會看到 一個升級 按鈕。
  3. 選取 [升級] 按鈕。 檢閱確認提示中的描述。 如果準備好執行移轉，請在提示中選取 [升級]。

手動管理移轉

以下步驟允許您手動遷移應用程式至 V2 API，若您不想使用先前描述的自動版本。

將秘密移至應用程式設定

若要將身分提供者密碼移至應用程式設定，請完成下列步驟。

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

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

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

    • Microsoft Entra： clientSecret
    • Google：googleClientSecret
    • Facebook：facebookAppSecret
    • X: twitterConsumerSecret
    • Microsoft 帳戶：microsoftAccountClientSecret

    重要

    秘密值是重要的安全性認證，應該謹慎處理。 不要在本地機器上分享或持久化這些值。

  2. 為每個秘密值建立位置固定的應用程式設定。 你可以選擇每個應用程式設定的名稱。 它的值應該與你在前一步取得的值相符，或參考你用該值建立的 Azure Key Vault 秘密 。

    要建立設定，你可以使用 Azure 入口網站，或為每個提供者執行以下指令的變體：

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

    注意

    此配置的應用程式設定應標示為插槽黏貼，表示在 插槽交換操作中不會在不同環境間移動。 這個設定是必要的，因為你的認證設定是綁定在環境上的。

  3. 建立名為 authsettings.json 的新 JSON 檔案。 請使用您先前取得的輸出，並從中移除所有秘密值。 將剩餘的輸出加入檔案，確保不包含任何秘密。 在某些情況下，配置中可能包含空字串的陣列。 請確保 microsoftAccountOAuthScopes 不會發生。 如果有，則將值改為 null。

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

    • Microsoft Entra： clientSecretSettingName
    • Google：googleClientSecretSettingName
    • Facebook：facebookAppSecretSettingName
    • X: twitterConsumerSecretSettingName
    • Microsoft 帳號： microsoftAccountClientSecretSettingName

    此操作後的設定檔案在此情況下可能如下所示，僅為 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. 請將此檔案提交為你應用程式的新認證/授權設定：

    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. 提交檔案後，請確認你的應用程式是否仍正常運作。

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

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

將設定切換至 Microsoft Entra 供應商

如果你現有的設定包含 Microsoft 帳號提供者，但沒有 Microsoft Entra 提供者，你可以將設定改成 Microsoft Entra 提供者，然後進行遷移：

  1. 請在 Azure 入口網站的 應用程式註冊 頁面，找到與你 Microsoft 帳號提供者相關的註冊。 可能在 「擁有的應用程式」 標題下。
  2. 請前往 認證（預覽） 頁面進行註冊。 在 Redirect URI 下，你應該會看到一個以 為結尾 /.auth/login/microsoftaccount/callback的條目。 複製此 URI。
  3. 新增一個與你剛複製的 URI 相符的 URI，但要以 /.auth/login/aad/callback 結尾。 此 URI 允許註冊用於 App Service 的驗證/授權設定。
  4. 前往門戶網站中的應用程式。 依序選取 [設定]>[驗證]。
  5. 收集 Microsoft 帳號提供者的組態設定。
  6. 使用 進階 管理模式設定 Microsoft Entra 提供者，並提供你在前一步收集的客戶端 ID 和客戶端秘密值。 對於 發行者網址，請使用 <authentication-endpoint>/<tenant-id>/v2.0. 請將 <authentication-endpoint> 替換為 你雲端環境的認證端點 （例如，"https://login.microsoftonline.com""；適用於全球 Microsoft Entra ID）。 用你的目錄（租戶）ID 替換<tenant-id>。
  7. 儲存設定後，請在瀏覽器中導覽到你網站的 /.auth/login/aad 端點並完成登入流程，測試登入流程。
  8. 此時，你已經成功複製了設定，但現有的 Microsoft 帳號提供者設定仍然存在。 在移除之前，請確保應用程式的所有部分都透過登入連結等方式參考 Microsoft Entra 供應商。 確認你的應用程式所有部分都正常運作。
  9. 在確認所有功能都能正常使用 Microsoft Entra 服務提供者後，就可以移除 Microsoft 帳號提供者的設定。

警告

可以透過修改 Microsoft Entra 應用程式註冊 的支援帳號類型 來合併兩種註冊。 然而，此配置會強制 Microsoft 帳號使用者產生新的同意提示，且這些使用者的身份聲明結構可能不同， sub 尤其是因為使用新的應用程式 ID 而改變數值。 除非你完全理解，否則我們不建議採用這種方法。 反而應該在 V2 API 介面中等候支援兩個註冊。

切換到 V2

完成前幾步後，進入 Azure 入口網站的應用程式。 選擇 驗證（預覽） 區塊。

或者，你也可以對網站資源下的config/authsettingsv2資源發起 PUT 請求。 有效載荷的結構與 檔案式設定中擷取的相同。

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

啟用驗證/授權時，平台中介軟體會插入 HTTP 要求管線中，如功能概觀所述。 隨著例行性平台更新，此平台中介軟體會定期更新功能並改善。 預設情況下，你的網頁或功能應用程式會運行在這個平台中介軟體的最新版本上。 這些自動更新始終保持向後相容性。 在罕見情況下，此自動更新會給 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，你可以透過 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 Functions 的版本，請參閱 Azure Functions 執行時版本概覽。

你可以在 Azure Cloud Shell 中執行此指令，方法是在前面的程式碼範例中選擇 Open Cloud Shell 。 你也可以在本地使用 Azure CLI 執行這個指令，然後執行 az 登入 。

後續步驟

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

  • Last updated on