Web 身份验证代理
本文介绍如何将通用 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 的流量添加防火墙规则。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈