Web 身份验证代理

项目
03/14/2024

本文介绍如何将通用 Windows 平台 (UWP) 应用连接到使用 OpenID 或 OAuth 等身份验证协议的联机标识提供者。 AuthenticateAsync 方法将请求发送给联机标识提供者，并取回描述应用有权访问的提供者资源的访问令牌。

注意

有关完整的有效代码示例，请克隆 GitHub 上的 WebAuthenticationBroker 存储库。

向联机提供商注册应用

你必须将你的应用注册到要连接到的联机标识提供商。可从标识提供商处找到如何注册应用的信息。注册后，联机提供商通常会向你提供应用的 ID 或私钥。

生成身份验证请求 URI

请求 URI 由以下内容组成：你将身份验证请求发送到联机提供商的地址，其中附有其他所需信息，例如应用 ID 或机密信息、用户在完成身份验证后发送的重定向 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。可从应用开发人员页面中找到应用的 SID，或通过调用 GetCurrentApplicationCallbackUri 方法达到此目的。

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”下启用 Operational 日志。此外，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 的信息。
- 导航完成：记录网页已完成加载。
- Meta 标记：记录何时遇到了 meta 标记（包括详细信息）。
- 导航终止：导航由用户终止。
- 导航错误：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 的流量添加防火墙规则。

通过