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

發行項
04/11/2024

針對內建的 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 和個人 Microsoft 帳戶的使用者。如果切換至 V2 API，則會使用 V1 Microsoft Entra 組態來設定 Microsoft 身分識別平台提供者。 V1 Microsoft 帳戶提供者會隨著移轉流程一起遷移，且繼續正常運作，但您應該改用較新的 Microsoft 身分識別平台模型。若要深入了解，請參閱支援 Microsoft 帳戶提供者註冊。

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

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

手動管理移轉

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

將秘密移至應用程式設定

使用 V1 API 取得現有的設定：
```
az webapp auth show -g <group_name> -n <site_name>
```
在產生的 JSON 承載中，記下您設定的每個提供者所使用的秘密值：
- Microsoft Entra： clientSecret
- Google：googleClientSecret
- Facebook：facebookAppSecret
- X: twitterConsumerSecret
- Microsoft 帳戶：microsoftAccountClientSecret
重要

秘密值是重要的安全性認證，應該謹慎處理。請勿分享這些值，也不要保存在本機電腦上。
為每個秘密值建立位置固定的應用程式設定。您可以選擇每個應用程式設定的名稱。其值應該符合您在上一個步驟中取得的值，或參考 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, X example
az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
```
注意

此組態的應用程式設定應該標示為位置固定，表示在位置交換作業期間不會在環境之間移動。這是因為驗證設定本身與環境密切相關。
建立名為 authsettings.json 的新 JSON 檔案。取得您先前收到的輸出，從中移除每個秘密值。將剩餘輸出寫入檔案，並確定不含任何秘密。在某些情況下，設定可能有包含空字串的陣列。請確定 microsoftAccountOAuthScopes 無此情形，否則，請將該值改為 null。

在 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/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"
    }   
}

提交此檔案給應用程式作為新的驗證/授權設定：

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

驗證應用程式在此動作之後仍如預期般運作。
刪除先前步驟中使用的檔案。

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

支援 Microsoft 帳戶提供者註冊

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

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

下一步

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

共用方式為