自定義登入和註銷 - Azure App Service

發行項
03/12/2024

本文說明如何在 App Service 中使用內建的驗證和授權，自定義使用者登入和註銷。

入口網站設定不提供轉折方式，向用戶呈現多個登入提供者（例如 Facebook 和 Twitter）。不過，將功能新增至您的應用程式並不容易。步驟概述如下：

首先，在 Azure 入口網站的 [驗證/ 授權] 頁面中，設定您想要啟用的每個識別提供者。

在 [要求未通過驗證時採取的動作] 中，選取 [允許匿名要求]（無動作）。

在 [登入] 頁面中，或導覽列，或任何其他應用程式位置，將登入連結新增至您啟用的每個提供者（/.auth/login/<provider>）。例如：

<a href="/.auth/login/aad">Log in with the Microsoft Identity Platform</a>
<a href="/.auth/login/facebook">Log in with Facebook</a>
<a href="/.auth/login/google">Log in with Google</a>
<a href="/.auth/login/twitter">Log in with Twitter</a>
<a href="/.auth/login/apple">Log in with Apple</a>

當使用者按兩下其中一個連結時，個別的登入頁面會開啟以登入使用者。

若要將使用者登入后重新導向至自定義 URL，請使用 post_login_redirect_uri 查詢字串參數（不要與身分識別提供者設定中的重新導向 URI 混淆）。例如，若要在登入之後巡覽使用者 /Home/Index ，請使用下列 HTML 程式代碼：

<a href="/.auth/login/<provider>?post_login_redirect_uri=/Home/Index">Log in</a>

在客戶端導向的登入中，應用程式會使用提供者特定的 SDK 將使用者登入識別提供者。然後，應用程式程式代碼會使用 HTTP POST 要求，將產生的驗證令牌提交至 App Service 進行驗證（請參閱驗證流程）。此驗證本身實際上不會授與您所需應用程式資源的存取權，但成功的驗證會為您提供可用來存取應用程式資源的會話令牌。

若要驗證提供者令牌，必須先使用所需的提供者來設定App Service 應用程式。在運行時間，從提供者擷取驗證令牌之後，將令牌張貼至 /.auth/login/<provider> 以進行驗證。例如：

POST https://<appname>.azurewebsites.net/.auth/login/aad HTTP/1.1
Content-Type: application/json

{"id_token":"<token>","access_token":"<token>"}

令牌格式會根據提供者稍有不同。如需詳細資訊，請參閱下表：

提供者值	要求本文中的必要專案	註解
`aad`	`{"access_token":"<access_token>"}`	`id_token`、 `refresh_token`和 `expires_in` 屬性是選擇性的。
`microsoftaccount`	`{"access_token":"<access_token>"}` 或 `{"authentication_token": "<token>"`	`authentication_token` 優先於 `access_token`。 `expires_in` 是選用屬性。向 Live 服務要求令牌時，請一律要求 `wl.basic` 範圍。
`google`	`{"id_token":"<id_token>"}`	`authorization_code` 是選用屬性。 `authorization_code`提供值會將存取令牌和重新整理令牌新增至令牌存放區。指定時， `authorization_code` 也可以選擇性地伴隨 `redirect_uri` 屬性。
`facebook`	`{"access_token":"<user_access_token>"}`	使用來自Facebook的有效使用者存取令牌。
`twitter`	`{"access_token":"<access_token>", "access_token_secret":"<access_token_secret>"}`

注意

App Service 驗證的 GitHub 提供者不支援自定義的登入和註銷。

如果成功驗證提供者令牌，API 會在響應主體中傳 authenticationToken 回，也就是您的會話令牌。

{
    "authenticationToken": "...",
    "user": {
        "userId": "sid:..."
    }
}

擁有此工作階段令牌之後，您可以將標頭新增 X-ZUMO-AUTH 至 HTTP 要求，以存取受保護的應用程式資源。例如：

GET https://<appname>.azurewebsites.net/api/products/1
X-ZUMO-AUTH: <authenticationToken_value>

註銷會話

用戶可以藉由將要求傳送 GET 至應用程式的 /.auth/logout 端點來起始註銷。要求 GET 會執行下列動作：

從目前的會話清除驗證 Cookie。
從令牌存放區刪除目前使用者的令牌。
針對 Microsoft Entra ID 和 Google，在識別提供者上執行伺服器端登出。

以下是網頁中的簡單登出連結：

<a href="/.auth/logout">Sign out</a>

根據預設，成功的登出會將用戶端重新導向至 URL /.auth/logout/complete。您可以新增 post_logout_redirect_uri 查詢參數來變更註銷后重新導向頁面。例如：

GET /.auth/logout?post_logout_redirect_uri=/index.html

建議您編碼的值 post_logout_redirect_uri。

使用完整 URL 時，URL 必須裝載在相同的網域中，或設定為應用程式允許的外部重新導向 URL。在下列範例中，若要重新導向至 https://myexternalurl.com 未載入於相同網域中的。

GET /.auth/logout?post_logout_redirect_uri=https%3A%2F%2Fmyexternalurl.com

在 Azure Cloud Shell 中執行下列命令：

az webapp auth update --name <app_name> --resource-group <group_name> --allowed-external-redirect-urls "https://myexternalurl.com"

保留 URL 片段

當使用者登入您的應用程式之後，他們通常會想要重新導向至相同頁面的相同區段，例如 /wiki/Main_Page#SectionZ。不過，由於 URL 片段（例如，#SectionZ）永遠不會傳送到伺服器，因此在 OAuth 登入完成並重新導向回到您的應用程式之後，預設不會保留這些片段。當使用者需要再次流覽至所需的錨點時，使用者就會獲得次佳的體驗。這項限制適用於所有伺服器端驗證解決方案。

在 App Service 驗證中，您可以跨 OAuth 登入保留 URL 片段。若要這樣做，請將名為 WEBSITE_AUTH_PRESERVE_URL_FRAGMENT 的應用程式設定設為 true。您可以在 Azure 入口網站中執行，或直接在 Azure Cloud Shell 中執行下列命令：

az webapp config appsettings set --name <app_name> --resource-group <group_name> --settings WEBSITE_AUTH_PRESERVE_URL_FRAGMENT="true"

Microsoft 帳戶和 Microsoft Entra 識別碼都可讓您從多個網域登入。例如，Microsoft 帳戶允許 outlook.com、 live.com 和 hotmail.com 帳戶。 Microsoft Entra ID 允許登入帳戶的任意數目自定義網域。不過，您可能想要將使用者直接加速到您自己的品牌 Microsoft Entra 登入頁面（例如 contoso.com）。若要建議登入帳戶的功能變數名稱，請遵循下列步驟。

在 https://resources.azure.com中，在頁面頂端，選取 [ 讀取/寫入]。
在左側瀏覽器中，流覽至訂<>用帳戶訂用帳戶名稱>resourceGroups<>resource-group-name 提供者>Microsoft.Web>sites><app-name>>>>config>authsettingsV2。
按一下 [編輯] 。

loginParameters新增具有domain_hint項目的陣列。

"identityProviders": {
    "azureActiveDirectory": {
        "login": {
            "loginParameters": ["domain_hint=<domain-name>"],
        }
    }
}

按兩下 [放置]。

此設定會將 domain_hint 查詢字串參數附加至登入重新導向 URL。

重要

用戶端可以在收到重新導向 URL 之後移除 domain_hint 參數，然後使用不同的網域登入。因此，雖然此函式很方便，但不是安全性功能。

授權或拒絕使用者

雖然 App Service 會處理最簡單的授權案例（也就是拒絕未經驗證的要求），但您的應用程式可能需要更精細的授權行為，例如只限制特定使用者群組的存取權。在某些情況下，您必須撰寫自定義應用程式程式代碼，以允許或拒絕登入使用者的存取權。在其他情況下，App Service 或您的識別提供者在不需要變更程式代碼的情況下，可能會有所説明。

伺服器層級
識別提供者層級
應用層級

伺服器層級（僅限 Windows 應用程式）

針對任何 Windows 應用程式，您可以編輯 Web.config 檔案來定義 IIS 網頁伺服器的授權行為。 Linux 應用程式不使用 IIS，且無法透過 Web.config 進行設定。

導覽到 https://<app-name>.scm.azurewebsites.net/DebugConsole
在 App Service 檔案的瀏覽器總管中，流覽至 site/wwwroot。 如果 Web.config 不存在，請選取>+ [新增檔案] 來建立它。
選取 Web.config 的鉛筆進行編輯。新增下列組態程式代碼，然後按兩下 [ 儲存]。如果 Web.config 已經存在，只要將 <authorization> 元素加入其中的所有專案即可。在元素中新增您想要允許的 <allow> 帳戶。
```
<?xml version="1.0" encoding="utf-8"?>
<configuration>
   <system.web>
      <authorization>
        <allow users="user1@contoso.com,user2@contoso.com"/>
        <deny users="*"/>
      </authorization>
   </system.web>
</configuration>
```

識別提供者層級

識別提供者可能會提供特定回合密鑰授權。例如：

針對 Azure App 服務，您可以直接在 Microsoft Entra 標識碼中管理企業層級存取。如需指示，請參閱如何移除使用者對應用程式的存取權。
針對 Google，屬於組織的 Google API 專案可以設定為只允許存取您組織中的使用者（請參閱 Google 的設定 OAuth 2.0 支援頁面）。

應用層級

如果其中一個其他層級未提供所需的授權，或平臺或身分識別提供者不受支援，您必須撰寫自定義程式碼，以根據使用者宣告授權使用者。

註銷會話

保留 URL 片段

授權或拒絕使用者

伺服器層級（僅限 Windows 應用程式）

識別提供者層級

應用層級

更多資源

其他資源

自定義登入和註銷 Azure App 服務 驗證

使用多個登入提供者

用戶端導向的登入

註銷會話

保留 URL 片段

限制登入帳戶的網域

授權或拒絕使用者

伺服器層級 （僅限 Windows 應用程式）

識別提供者層級

應用層級

更多資源

其他資源

自定義登入和註銷 Azure App 服務驗證

伺服器層級（僅限 Windows 應用程式）