Web 身份验证代理

2025-06-10

本文介绍如何将通用 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 方法找到应用的 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 在包含 HttpStatusCode 的 URL 上发生错误。
- 导航结束：遇到终止的网址。

琴师

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 的传入流量添加防火墙规则。

通过