Web 驗證代理人

發行項
07/05/2024

本文說明如何將您的通用 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 參數，並將您希望使用者重新導向到的 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 驗證代理程式會將唯一的字串附加到使用者代理字串，以在 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\Image File Execution Options\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 的傳入流量新增防火牆規則。

共用方式為