了解 Web 驗證代理人工作流程和偵錯 (HTML)

發行項
12/11/2015

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱最新文件 ]

您可以使用 Web 驗證代理人來為使用者啟用單一登入 (SSO)，即可順暢地在多個 Windows 市集應用程式間向單一服務進行驗證。Web 驗證代理人支援 OAuth 與 OpenID 網際網路驗證通訊協定，因此您可以將應用程式與提供使用者驗證的 Web 服務整合。這可讓您在像是 Facebook、Flickr、Google 及 Twitter 等應用程式中使用使用者識別。

當應用程式呼叫 Web 驗證代理人時，使用者會看到一個對話方塊，裡面會顯示登入所需的網頁。服務提供者需讓使用者明確同意該驗證，通常會包含一個 [讓我保持登入] 選項。提供者也必須讓使用者清楚知道會如何使用他們的身分識別，通常是在登入頁面上提供一個隱私權聲明的連結。當使用者完成這些步驟後，對話方塊就會消失，使用者可以繼續使用應用程式。

下圖顯示強制回應對話方塊的範例。

使用 Web 驗證代理人的優點

Web 驗證代理人提供下列優點：

易於使用的程式設計介面，可節省應用程式開發人員在應用程式內裝載瀏覽器控制項的時間。
將提供者的網頁與 Windows 8 使用者介面整合。如需線上提供者的詳細資訊，請參閱線上提供者的 Web 驗證代理人。
提供與應用程式隔離的使用者認證。
使用線上提供者進行單一登入的原生支援。

Web 驗證代理人的運作方式

Web 驗證代理人是應用程式和驗證服務之間的代理人或協助者。它包含一組 API、一個代理人以及一部 Web 主機。您的應用程式會使用 API 與代理人通訊。代理人會在獨立的應用程式容器中建立新的 Web 主機處理程序。代理人會與應用程式通訊、組合使用者介面 (UI) 以及控制 Web 驗證主機的週期。Web 驗證主機會呈現線上驗證提供者網站的網頁。

下圖說明使用 Web 驗證代理人的資訊流程。

Web 驗證代理人的資料流程

以下是使用 Web 驗證代理人的標準工作流程：

1. 您的應用程式使用 WebAuthenticationBroker.AuthenticateAsync 方法叫用 Web 驗證代理人。您在驗證呼叫完成時提供起始要求 URI 與回呼 URI。這些會對應至 OAuth 2.0 通訊協定的「授權端點 URI」和「重新導向 URI」。OpenID 通訊協定及舊版 OAuth 中的概念類似。
代理人會建立一個呼叫應用程式必須強制回應的系統對話方塊。
代理人會選取專用的應用程式容器 (有別於系統上的呼叫應用程式或任何其他應用程式)，然後清除任何永續性 Cookie。注意這個應用程式容器絕不會同時在兩個應用程式之間共用，除非代理人以單一登入 (SSO) 模式啟動。
代理人會在選取的應用程式容器中啟動 Web 驗證主機。
代理人會將主機的視窗與先前建立的對話方塊連接。主機視窗負責呈現網頁內容。
Web 驗證主機則會瀏覽要求 URI。這通常是一個登入頁面。
當使用者按一下連結或提交資訊來與線上提供者網站互動時，主機會在瀏覽 URI 之前，先使用應用程式提供的回呼 URI 檢查每個 URI 是否有相符網站。
如果找到相符的網站，主機會結束瀏覽，然後通知代理人。
代理人會取消對話方塊，清除應用程式容器中主機所建立的任何永續性 Cookie，然後將通訊協定資料傳回應用程式。

Web 驗證代理人單一登入的運作方式

Web 驗證代理人透過允許永續性 Cookie 存留在特殊用途的 SSO 應用程式容器中來啟用單一登入 (SSO)。為了使用此容器，您的應用程式可以呼叫不會取用回呼 URI 之 AuthenticateAsync 方法的超載。起始的重新導向 URL 格式需為 "ms-app://<SID>"，其中的 <SID> 符合呼叫套件的 SID。您可以在驗證服務將您每個應用程式的 SID 註冊為有效的重新導向 URL (也稱為「重新導向端點」)。

例如，Fabrikam 是使用 Contoso 服務的 Windows 市集應用程式的開發工具。在開發階段，Fabrikam 會向 Windows 開發人員中心登錄它的應用程式，接著就會收到一個唯一 SID。接著 Fabrikam 會在 Contoso.com 驗證服務將它們的應用程式 SID 註冊為有效的重新導向 URL。Fabrikam 會將它的兩個 SID 註冊為重新導向 URL，其中一個是 "ms-app://S-1-5-4321"。

在執行階段，Fabrikam 的 Windows 市集應用程式會以 SSO 模式叫用 Web 驗證代理人。在處理要求的過程中，Contoso.com 會確認重新導向 URL 是否包含在該組登錄的 URL 中。在 Contoso 驗證使用者之後，就會重新導向到要求的重新導向 URL，後面加上存取權杖："ms-app://S-1-5-4321?token=ABC"。當 Web 驗證代理人遇到這種格式並且符合呼叫應用程式 SID 的 URL，就會將查詢字串中所包含的權杖傳回，或將資料張貼回應用程式。

如果有任何 Cookie 已經建立在 SSO 應用程式容器中，使用者就不需要登入 Contoso。如果有任何其他應用程式嘗試模擬 Fabrikam 的應用程式，就會失敗，因為 Contoso 會透過確認所要求的是否是其中一個已經登錄的重新導向 URL 來驗證應用程式的識別資料，而 Web 驗證代理人則會確認只有共用 SID 與 Contoso 要重新導向的 SID 相同的應用程式會取得通訊協定資料。

疑難排解 Web 驗證代理人

有數種方法可以為您的應用程式疑難排解 Web 驗證代理人 API 的問題，包括使用 Fiddler 檢閱作業日誌和檢閱 Web 要求與回應。

作業記錄

通常您可以透過使用作業記錄來判斷哪裡出問題。有一個專用的事件記錄檔通道 Microsoft-Windows-WebAuth\Operational，可供網站開發人員了解 Web 驗證代理人如何處理他們的網頁。如果要啟用作業記錄，請啟動 eventvwr.exe，然後啟用 [應用程式及服務\Microsoft\Windows\WebAuth] 底下的 [作業] 記錄。此外，Web 驗證代理人還會在使用者代理字串後面附加一個唯一字串，以便在網頁伺服器上識別自己。這個字串是 "MSAuthHost/1.0"。請注意，版本號碼在日後可能會有變更，因此在程式碼中不應該依據該版本號碼。完整的使用者代理字串範例如下：

User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)

使用作業記錄範例

啟用作業記錄
執行 Contoso 社交應用程式
產生的記錄項目可以用來進一步了解 Web 驗證代理人的行為。在此情況下，這些可能包括：
- 瀏覽開始：記錄 AuthHost 何時啟動，並且包含開始和終止 URL 的相關資訊。
- 瀏覽完成：記錄網頁載入完成。
- Meta 標記：記錄何時遇到 meta-tag，包含詳細資料。
- 瀏覽終止：使用者終止瀏覽。
- 瀏覽錯誤：AuthHost 在 URL 遇到瀏覽錯誤，包含 HttpStatusCode。
- 瀏覽結束：遇到終止 URL。

將 Fiddler 與 Web 驗證代理人搭配使用

Fiddler Web 偵錯工具可以與 Windows 8 應用程式搭配使用。

由於 AuthHost 是在自己的應用程式容器中執行以給予私人網路功能，因此您必須設定登錄機碼： Windows 登錄編輯程式 5.00 版

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 00000001
- Data type
  DWORD

為 AuthHost 新增一個規則，因為它是產生輸出流量的主機。

CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.a.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
D:\Windows\System32>CheckNetIsolation.exe LoopbackExempt -s
List Loopback Exempted AppContainers
[1] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
    SID:  S-1-15-2-1973105767-3975693666-32999980-3747492175-1074076486-3102532000-500629349
[2] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
    SID:  S-1-15-2-166260-4150837609-3669066492-3071230600-3743290616-3683681078-2492089544
[3] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.a.p_8wekyb3d8bbwe
    SID:  S-1-15-2-3506084497-1208594716-3384433646-2514033508-1838198150-1980605558-3480344935

將連入流量防火牆規則新增到 Fiddler。

如需詳細資訊，請參閱將 Fiddler Web 偵錯工具與 Windows 市集應用程式搭配使用的部落格。

共用方式為