網路驗證仲介

2025-06-10

本文說明如何將通用 Windows 平臺（UWP）應用程式連線到使用 OpenID 或 OAuth 等驗證通訊協定的線上識別提供者。 AuthenticateAsync 方法會將要求傳送至在線識別提供者，並取得存取令牌，描述應用程式可存取的提供者資源。

備註

如需完整的運作程式碼範例，請複製 GitHub 上的 WebAuthenticationBroker 存放庫。

向在線提供者註冊您的應用程式

您必須向您要連線的線上識別提供者註冊您的應用程式。您可以瞭解如何從識別提供者註冊您的應用程式。註冊之後，在線提供者通常會提供您應用程式的標識碼或秘密密鑰。

建置驗證要求 URI

要求 URI 包含您傳送驗證要求給在線提供者的地址，這些位址附加了其他必要資訊，例如應用程式識別碼或秘密、完成驗證之後傳送使用者的重新導向 URI，以及預期的回應類型。您可以從提供者找出需要哪些參數。

要求 URI 會作為 requestUri 參數傳送到 AuthenticateAsync 方法。它必須是安全地址（必須以 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 參數，並將您要使用者重新導向至的 URI 作為 callbackUri 參數。

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 Phone 8.1 為目標的應用程式所設計，且從 Windows 10 開始已被取代。

使用單一登錄（SSO）進行連線。

根據預設，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 Web 調試程式可以搭配應用程式使用。如需詳細資訊，請參閱 Fiddler 文件

由於 AuthHost 會在自己的應用程式容器中執行，因此，若要賦予其專用網路功能，您必須設定一個登錄機碼：Windows 登錄編輯器 5.00 版。

\ HKEY_LOCAL_MACHINE軟體\\ MicrosoftWindows 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。

共用方式為