WSFederationAuthenticationModule 类
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
WSFederationAuthenticationModule是一个 HTTP 模块，用于通过对传入请求强制实施联合身份验证设置来保护 ASP.NET 应用程序。 WSFederationAuthenticationModule 是 WIF 提供的现成可用的主要模块，用于在 ASP.NET 应用程序中处理基于声明的标识访问。
WSFederationAuthenticationModule 引发几个事件，它允许 ASP.NET 开发人员更改默认行为和控制身份验证和声明处理如何发生的细节。 WSFederationAuthenticationModule 功能被分为任务具体的方法。
public ref class WSFederationAuthenticationModule : System::IdentityModel::Services::HttpModuleBasepublic class WSFederationAuthenticationModule : System.IdentityModel.Services.HttpModuleBasetype WSFederationAuthenticationModule = class
inherit HttpModuleBasePublic Class WSFederationAuthenticationModule
Inherits HttpModuleBase- 继承
示例
void Application_Start(object sender, EventArgs e)
{
// Code that runs on application startup
//SUBSCRIBE TO WSFAM EVENTS
FederatedAuthentication.WSFederationAuthenticationModule.AuthorizationFailed += new EventHandler<AuthorizationFailedEventArgs>(WSFederationAuthenticationModule_AuthorizationFailed);
FederatedAuthentication.WSFederationAuthenticationModule.RedirectingToIdentityProvider += new EventHandler<RedirectingToIdentityProviderEventArgs>(WSFederationAuthenticationModule_RedirectingToIdentityProvider);
FederatedAuthentication.WSFederationAuthenticationModule.SecurityTokenReceived += new EventHandler<SecurityTokenReceivedEventArgs>(WSFederationAuthenticationModule_SecurityTokenReceived);
FederatedAuthentication.WSFederationAuthenticationModule.SecurityTokenValidated += new EventHandler<SecurityTokenValidatedEventArgs>(WSFederationAuthenticationModule_SecurityTokenValidated);
FederatedAuthentication.WSFederationAuthenticationModule.SessionSecurityTokenCreated += new EventHandler<SessionSecurityTokenCreatedEventArgs>(WSFederationAuthenticationModule_SessionSecurityTokenCreated);
FederatedAuthentication.WSFederationAuthenticationModule.SignedIn += new EventHandler(WSFederationAuthenticationModule_SignedIn);
}
void WSFederationAuthenticationModule_SignedIn(object sender, EventArgs e)
{
//Anything that's needed right after succesful session and before hitting the application code goes here
System.Diagnostics.Trace.WriteLine("Handling SignIn event");
}
void WSFederationAuthenticationModule_SessionSecurityTokenCreated(object sender, SessionSecurityTokenCreatedEventArgs e)
{
//Manipulate session token here, for example, changing its expiration value
System.Diagnostics.Trace.WriteLine("Handling SessionSecurityTokenCreated event");
System.Diagnostics.Trace.WriteLine("Key valid from: " + e.SessionToken.KeyEffectiveTime);
System.Diagnostics.Trace.WriteLine("Key expires on: " + e.SessionToken.KeyExpirationTime);
}
void WSFederationAuthenticationModule_SecurityTokenValidated(object sender, SecurityTokenValidatedEventArgs e)
{
//All vlidation SecurityTokenHandler checks are successful
System.Diagnostics.Trace.WriteLine("Handling SecurityTokenValidated event");
}
void WSFederationAuthenticationModule_SecurityTokenReceived(object sender, SecurityTokenReceivedEventArgs e)
{
//Augment token validation with your cusotm validation checks without invalidating the token.
System.Diagnostics.Trace.WriteLine("Handling SecurityTokenReceived event");
}
void WSFederationAuthenticationModule_AuthorizationFailed(object sender, AuthorizationFailedEventArgs e)
{
//Use this event to report more details regarding the ahorization failure
System.Diagnostics.Trace.WriteLine("Handling AuthorizationFailed event");
}
void WSFederationAuthenticationModule_RedirectingToIdentityProvider(object sender, RedirectingToIdentityProviderEventArgs e)
{
//Use this event to programmatically modify the sign-in message to the STS.
System.Diagnostics.Trace.WriteLine("Handling RedirectingToIdentityProvider event");
}
注解
类 WSFederationAuthenticationModule 实现称为 WS-Federation 身份验证模块的 HTTP 模块 (WSFAM) 。 WSFAM 由 Windows Identity Foundation (WIF) 实现。 WSFAM 通过 web.config 文件中的条目添加到 ASP.NET 管道。 它派生自 HttpModuleBase，后者实现 IHttpModule。 它向 ASP.NET 运行时注册以侦 EndRequest 听 和 AuthenticateRequest 事件。 侦 EndRequest 听事件后，WSFAM 可将客户端重定向到安全令牌服务， (STS) 在请求的资源上授权失败时获取安全令牌。 通过侦 AuthenticateRequest 听事件，WSFAM 可以监视来自包含所请求令牌的 STS 的响应的 HTTP 请求。 当此类令牌存在且有效时，它会使用令牌中存在的声明为经过身份验证的用户创建 ClaimsPrincipal 实例。
使用 WSFAM 时，会话管理由会话身份验证模块 (SAM) （类的 SessionAuthenticationModule 实例）或派生自它的类的会话身份验证模块提供。 SAM 还会添加到配置文件中的 ASP.NET 管道。 SAM 监视 (会话) Cookie 的身份验证请求。 当这些 Cookie 存在且有效时，模块将从 SessionSecurityToken 中提取ClaimsPrincipal经过身份验证的用户的 HttpContext.User ，并设置 属性和线程主体Thread.CurrentPrincipal属性。
WSFAM 提供：
ASP.NET 应用程序能够使用 WS-Federation 协议将身份验证外包给安全令牌服务， (STS) 。 标识可以跨一个或多个标识领域联合，并涉及多个 STS。
ASP.NET 应用程序的基于声明的标识。 在身份验证期间，WSFAM 根据 STS 发送的安全令牌中的声明生成主体，并将此声明主体设置为线程主体。 然后，可以使用此主体对代码中表示的用户做出进一步的授权、表示和逻辑决策。
WSFAM 公开多个属性，这些属性提供用于 WS-Federation 登录和注销请求的默认消息参数。 这些属性通常是从配置文件中的 <wsFederation> 元素初始化的。 其中最重要的属性是：
属性 Issuer ，指定要向其发送 WS-Federation 登录和注销请求的安全令牌服务 (STS) 的地址。
属性 Realm ，指定要在 WS-Federation 登录请求中使用的 wtrealm 参数。 wtrealm 参数标识信赖方的安全领域， (RP) STS 应用程序。
还可以通过为事件提供事件处理程序委托 RedirectingToIdentityProvider ，根据每个请求更改登录消息参数。
两个属性控制模块的行为。 这两个属性通常也从 <wsFederation> 配置中的 元素初始化。
属性 PassiveRedirectEnabled 指定模块是否应执行到 STS 的被动重定向以进行身份验证。
属性 PersistentCookiesOnPassiveRedirects 指定会话是否应是永久性的。 如果此属性设置为 true，则 SAM 用于将会话 Cookie 写入客户端。 在来自客户端的后续请求中，SAM 使用会话 Cookie 中保留的令牌来提供身份验证。
WSFAM 在登录和注销期间引发多个事件，使 ASP.NET 开发人员能够更改模块的默认行为，并控制身份验证和声明处理方式的详细信息。
在将 WS-Federation 登录请求发送到 STS 之前，将引发以下事件：
AuthorizationFailed：在启用被动重定向且请求的资源上的授权失败时引发。
RedirectingToIdentityProvider：在 WSFAM 将 WS-Federation 登录请求发送到 STS 之前引发。 可以使用此事件更改登录请求中的参数。
从 STS 收到登录响应 (颁发安全令牌) 时，将引发以下事件：
SecurityTokenReceived：在从响应中读取 STS 发送的安全令牌后引发。
SecurityTokenValidated：在验证令牌后引发。 可以使用此事件筛选、转换声明或将声明添加到从安全令牌创建的声明主体 (ClaimsPrincipal) 。
SessionSecurityTokenCreated：在会话令牌之前引发 (SessionSecurityToken 从声明主体创建的) 用于设置线程主体和当前用户，并写入会话 Cookie。 使你有机会修改会话令牌或启用或禁用写入会话 Cookie。
SignedIn：在设置线程主体和当前用户之后，在身份验证结束时引发。
SignInError：如果登录期间发生异常，则引发。 可以取消请求并防止异常返回给调用方。
注销会话或处理 wsignoutcleanup1.0) (WS-Federation 注销清理请求时，将引发以下事件：
SigningOut：在删除会话之前引发，使你能够执行任何可能依赖于会话的清理或取消注销。
SignedOut：在删除会话后引发。
SignOutError：如果在注销期间发生异常，则引发。可以取消注销并防止异常返回给调用方。
注意
通过调用 FederatedSignOut 方法在 STS 注销时，不会引发注销事件。
可通过两种方式使用 WSFAM 登录到 STS。 第一种是通过 属性启用被动重定向 PassiveRedirectEnabled 。 在这种情况下，如果对请求的资源授权失败，而不是向客户端返回 401:Access Denied 响应，WSFAM 会从其属性生成 WS-Federation 登录请求消息，并将客户端重定向到 STS 以检索安全令牌。 第二种方法是通过从应用程序中的网页或自定义控件调用 SignIn 方法，将客户端显式重定向到 STS。 方法 SignIn 还使用 WSFAM 的属性来构造登录请求。
可以使用任何重载 SignOut 方法注销会话。 这会删除客户端上的会话 Cookie。 它不会将 WS-Federation 注销消息 (“wsignout1.0”) 发送到 STS。 若要在 STS 注销，必须使用 FederatedSignOut 方法。
WSFAM 通过删除其与客户端的会话 (“wsignoutcleanup1.0”) 处理 WS-Federation 注销清理请求。 如果未设置注销清理消息中的 wreply 参数，则 WSFAM 会将绿色检查标记的图像返回到发送消息的 STS。 STS 可以使用此功能作为 RP 已完成注销的确认。
WSFAM 通过多种特定于任务的方法公开其功能（例如请求处理管道）。 可以在派生类中重写这些方法，以更改 WSFAM 的行为。
若要使用，必须将 模块添加到管道，如以下 XML 所示：
<configuration>
<system.webServer>
<modules>
<add name="WsFederationAuthenticationModule" type="System.IdentityModel.Services.WSFederationAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
</modules>
</system.webServer>
</configuration>
配置后， WSFederationAuthenticationModule 会在处理 HTTP 请求的不同阶段引发事件。 ASP.NET 开发人员可以在 global.asax 文件中处理这些事件。
构造函数
| WSFederationAuthenticationModule() |
由派生类中的构造函数调用，用于初始化 WSFederationAuthenticationModule 类。 |
属性
| AuthenticationType |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 wauth 参数的值。 |
| FederationConfiguration |
获取或设置对于当前模块有效的 FederationConfiguration 对象。 (继承自 HttpModuleBase) |
| Freshness |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 wfresh 参数的值。 |
| HomeRealm |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 whr 参数的值。 |
| Issuer |
获取或设置标识安全标记的预期颁发者的 URI。 |
| PassiveRedirectEnabled |
获取或设置指定是否启用模块以启动 WS-Federation 协议重定向的值。 |
| PersistentCookiesOnPassiveRedirects |
获取或设置指定是否对成功的身份验证颁发一致的会话 Cookie 的值。 |
| Policy |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 wp 参数的值。 |
| Realm |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 wtrealm 参数的值。 |
| Reply |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 wreply 参数的值。 |
| Request |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 wreq 参数的值。 |
| RequestPtr |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 wreqptr 参数的值。 |
| RequireHttps |
获取或设置指定与安全令牌服务 (STS) 的通信是否必须使用 HTTPS 协议的值。 |
| Resource |
获取或设置 WS 联合身份验证登录请求（“wsignin1.0”）中使用的 wres 参数的值。 |
| SignInContext |
获取或设置应用程序的特定上下文值，该值包含在 WS 联合身份验证登录请求的 wctx 参数中。 |
| SignInQueryString |
获取或设置包含要在 WS 联合身份验证登录请求（“wsignin1.0”）中发送的额外参数的查询字符串。 |
| SignOutQueryString |
获取或设置询问字符串，该字符串包含 WS 联合身份验证注销请求（“wsignout1.0”）中将被发送的额外参数。 |
| SignOutReply |
获取或设置在 WS 联合身份验证注销请求（“wsignout1.0”）期间使用的 wreply 参数的值。 |
| XmlDictionaryReaderQuotas |
获取设置序列化 WS-Federation 响应消息以获取安全令牌服务 (STS) 使用的令牌时要使用的 XmlDictionaryReaderQuotas 对象。 |
方法
事件
| AuthorizationFailed |
当模块确定是否应该重定向用户配置的颁布者验证时发生。 |
| RedirectingToIdentityProvider |
当模块即将重定向用户标识提供程序时发生。 |
| SecurityTokenReceived |
当安全标记已从安全标记服务 (STS) 获得时发生。 |
| SecurityTokenValidated |
但是在会话安全标记已创建之前,安全标记服务 (STS) 已被验证的安全标记后发生。 |
| SessionSecurityTokenCreated |
当会话安全标记已从安全标记服务标记 (STS) 创建时发生。 |
| SignedIn |
在用于登录之后发生。 |
| SignedOut |
只在注销期间删除会话后发生。 |
| SignInError |
当登录过程中出现错误时引发。 |
| SigningOut |
在注销期间删除会话前发生。 |
| SignOutError |
当注销过程中出现错误时引发。 |
适用于
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈