Web 驗證代理人
本文說明如何將您的 通用 Windows 平台 （UWP） 應用程式連線到使用 OpenID 或 OAuth 等驗證通訊協定的線上識別提供者。 AuthenticateAsync 方法會將要求傳送至線上識別提供者，並取得說明應用程式可存取提供者資源的存取權杖。
注意
如需完整的運作程式碼範例，請複製 GitHub 上的 WebAuthenticationBroker 存放庫。
向在線提供者註冊您的應用程式
您必須向您要連線的線上識別提供者註冊您的應用程式。 您可以瞭解如何從識別提供者註冊您的應用程式。 註冊之後，在線提供者通常會提供您應用程式的標識碼或秘密密鑰。
建置驗證要求 URI
要求 URI 包含您傳送驗證要求給在線提供者的地址，這些位址附加了其他必要資訊，例如應用程式識別碼或秘密、完成驗證之後傳送使用者的重新導向 URI，以及預期的回應類型。 您可以從提供者找出需要哪些參數。
要求 URI 會以 AuthenticateAsync 方法的 requestUri 參數的形式傳送。 它必須是安全地址（必須以 https://開頭）
下列範例示範如何建置要求 URI。
string startURL = "https://<providerendpoint>?client_id=<clientid>&scope=<scopes>&response_type=token";
string endURL = "http://<appendpoint>";
System.Uri startURI = new System.Uri(startURL);
System.Uri endURI = new System.Uri(endURL);
連線 至在線提供者
您可以呼叫 AuthenticateAsync 方法來連線到在線識別提供者並取得存取令牌。 方法會採用在上一個步驟中建構的 URI 作為 requestUri 參數，以及您想要將使用者重新導向為 callbackUri 參數的 URI。
string result;
try
{
var webAuthenticationResult =
await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync(
Windows.Security.Authentication.Web.WebAuthenticationOptions.None,
startURI,
endURI);
switch (webAuthenticationResult.ResponseStatus)
{
case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
// Successful authentication.
result = webAuthenticationResult.ResponseData.ToString();
break;
case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
// HTTP error.
result = webAuthenticationResult.ResponseErrorDetail.ToString();
break;
default:
// Other error.
result = webAuthenticationResult.ResponseData.ToString();
break;
}
}
catch (Exception ex)
{
// Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here.
result = ex.Message;
}
警告
除了 AuthenticateAsync 之外，Windows.Security.Authentication.Web 命名空間還包含 AuthenticateAndContinue 方法。 請勿呼叫此方法。 它專為僅以 Windows 電話 8.1 為目標的應用程式所設計，且從 Windows 10 開始已被取代。
使用單一登入 連線 。
根據預設，Web 驗證代理程式不允許保存 Cookie。 因此，即使應用程式使用者指出他們想要保持登入狀態（例如，藉由在提供者的登入對話框中選取複選框），每次想要存取該提供者的資源時，他們都必須登入。 若要使用 SSO 登入，您的在線識別提供者必須已啟用 Web 驗證代理人的 SSO，而且您的應用程式必須呼叫不採用 callbackUri 參數的 AuthenticateAsync 多載。 這可讓 Web 驗證代理程式儲存保存的 Cookie，如此一來，相同應用程式的未來驗證呼叫就不需要使用者重複登入（用戶實際上已「登入」，直到存取令牌到期為止）。
若要支援 SSO，在線提供者必須允許您在 表單 ms-app://<appSID>中註冊重新導向 URI，其中 <appSID> 是應用程式的 SID。 您可以從應用程式的應用程式開發人員頁面，或呼叫 GetCurrentApplicationCallbackUri 方法，找到應用程式的 SID。
string result;
try
{
var webAuthenticationResult =
await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync(
Windows.Security.Authentication.Web.WebAuthenticationOptions.None,
startURI);
switch (webAuthenticationResult.ResponseStatus)
{
case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
// Successful authentication.
result = webAuthenticationResult.ResponseData.ToString();
break;
case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
// HTTP error.
result = webAuthenticationResult.ResponseErrorDetail.ToString();
break;
default:
// Other error.
result = webAuthenticationResult.ResponseData.ToString();
break;
}
}
catch (Exception ex)
{
// Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here.
result = ex.Message;
}
偵錯
有數種方式可針對 Web 驗證代理人 API 進行疑難解答，包括檢閱作業記錄，以及使用 Fiddler 檢閱 Web 要求和回應。
作業記錄
您通常可以使用作業記錄來判斷哪些項目無法運作。 有一個專用的事件記錄通道 Microsoft-Windows-WebAuth\Operational，可讓網站開發人員瞭解 Web 驗證代理人如何處理其網頁。 若要啟用，請啟動eventvwr.exe，並在 Application and Services\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 的相關信息。
- 流覽完成：記錄載入網頁的完成。
- 中繼標籤：遇到中繼標記時記錄包括詳細數據。
- 瀏覽終止：使用者終止流覽。
- 流覽錯誤：AuthHost 在 URL 上遇到導覽錯誤，包括 HttpStatusCode。
- 瀏覽結束：遇到終止 URL。
Fiddler
Fiddler Web 調試程式可以搭配應用程式使用。 如需詳細資訊，請參閱 Fiddler 檔
由於 AuthHost 會在自己的應用程式容器中執行，因此您必須設定登錄機碼：Windows 登錄編輯器 5.00 版
HKEY_LOCAL_MACHINE SOFTWARE\Microsoft\Windows NT\CurrentVersion\映射檔執行選項\authhost.exe\EnablePrivateNetwork = 00000001 \
如果您沒有此登入機碼，您可以在具有系統管理員許可權的命令提示字元中建立它。
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f新增 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。
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應