WSFederationAuthenticationModule Class

Definition

public ref class WSFederationAuthenticationModule : System::IdentityModel::Services::HttpModuleBase

public class WSFederationAuthenticationModule : System.IdentityModel.Services.HttpModuleBase

type WSFederationAuthenticationModule = class
    inherit HttpModuleBase

Public Class WSFederationAuthenticationModule
Inherits HttpModuleBase

Inheritance

Object

HttpModuleBase

WSFederationAuthenticationModule

Examples

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");
}

Remarks

The WSFederationAuthenticationModule class implements an HTTP module known as the WS-Federation Authentication Module (WSFAM). The WSFAM is implemented out of the box by Windows Identity Foundation (WIF). The WSFAM is added to the ASP.NET pipeline by making an entry in the web.config file. It derives from HttpModuleBase, which implements IHttpModule. It registers with the ASP.NET runtime to listen for the EndRequest and AuthenticateRequest events. Listening to the EndRequest event, lets the WSFAM redirect clients to a security token service (STS) to obtain a security token when authorization fails on a requested resource. Listening to the AuthenticateRequest event enables the WSFAM to monitor HTTP requests for a response from the STS that contains the requested token. When such a token is present and valid, it creates an instance of ClaimsPrincipal for the authenticated user using the claims that are present in the token.

When using the WSFAM, session management is provided by a session authentication module (SAM), which is an instance of the SessionAuthenticationModule class, or a class derived from it. The SAM is also added to the ASP.NET pipeline in the configuration file. The SAM monitors requests for authentication (session) cookies. When these cookies are present and valid, the module extracts the ClaimsPrincipal for the authenticated user from the SessionSecurityToken and sets the HttpContext.User property and the thread principal Thread.CurrentPrincipal properties.

The WSFAM provides:

• The ability for an ASP.NET application to outsource authentication to a security token service (STS) by using the WS-Federation protocol. Identity can be federated across one or more identity realms and involve multiple STSs.

• Claims-based identity for ASP.NET applications. During authentication, the WSFAM builds a principal from the claims in the security token sent by the STS and sets this claims principal as the thread principal. You can then use this principal to make further authorization, presentation, and logic decisions about the user it represents in your code.

The WSFAM exposes several properties that provide default message parameters to use on WS-Federation sign-in and sign-out requests. These properties are typically initialized from the <wsFederation> element in a configuration file. The most important of these properties are:

• The Issuer property, which specifies the address of the security token service (STS) to which to send WS-Federation sign-in and sign-out requests.

• The Realm property, which specifies the wtrealm parameter to use in WS-Federation sign-in requests. The wtrealm parameter identifies the security realm of the relying party (RP) application to the STS.

Sign-in message parameters can also be changed on a per-request basis by providing an event-handler delegate for the RedirectingToIdentityProvider event.

Two properties control the behavior of the module. Both of these properties are also typically initialized from the <wsFederation> element in configuration.

• The PassiveRedirectEnabled property specifies whether the module should perform passive redirects to the STS for authentication.

• The PersistentCookiesOnPassiveRedirects property specifies whether sessions should be persistent. If this property is set true, the SAM is used to write a session cookie to the client. On subsequent requests from the client, the SAM provides authentication by using the token persisted in the session cookie.

The WSFAM raises several events during sign-in and sign-out, which allow ASP.NET developers to change the default behavior of the module and control the details of how authentication and claims processing take place.

The following events are raised before the WS-Federation sign-in request is sent to the STS:

• AuthorizationFailed: Raised when passive redirect is enabled and authorization fails on a requested resource.

• RedirectingToIdentityProvider: Raised just before the WSFAM sends the WS-Federation sign-in request to the STS. You can use this event to change the parameters in the sign-in request.

The following events are raised when a sign-in response (issued security token) is received from the STS:

• SecurityTokenReceived: Raised just after the security token sent by the STS is read from the response.

• SecurityTokenValidated: Raised just after the token has been validated. You can use this event to filter, transform, or add claims to the claims principal (ClaimsPrincipal) created from the security token.

• SessionSecurityTokenCreated: Raised just before the session token (SessionSecurityToken) created from the claims principal is used to set the thread principal and current user and is written to the session cookie. Gives you an opportunity to modify the session token or enable or disable writing the session cookie.

• SignedIn: Raised at the end of the authentication just after the thread principal and current user have been set.

• SignInError: Raised if an exception occurs during sign-in. You can cancel the request and prevent the exception from being returned to the caller.

When signing out of a session or when processing a WS-Federation sign-out clean-up request (wsignoutcleanup1.0), the following events are raised:

• SigningOut: Raised just before the session is deleted to enable you to perform any cleanup that might depend on the session or to cancel sign-out.

• SignedOut: Raised just after the session has been deleted.

• SignOutError: Raised if an exception occurs during sign-out. You can cancel sign-out and prevent the exception from being returned to the caller.

There are two ways of signing in to an STS using WSFAM. The first is by enabling passive redirects through the PassiveRedirectEnabled property. In this case, when authorization fails on a requested resource, rather than returning a 401:Access Denied response to the client, WSFAM builds a WS-Federation sign-in request message from its properties and redirects the client to the STS to retrieve a security token. The second way is to explicitly redirect the client to the STS by calling the SignIn method from a web page or custom control in your application. The SignIn method also uses the properties of the WSFAM to construct the sign-in request.

Any of the overloaded SignOut methods can be used to sign out of the session. This deletes the session cookie on the client. It does not send a WS-Federation sign-out message ("wsignout1.0") to the STS. To sign-out at the STS, you must use the FederatedSignOut method.

The WSFAM handles WS-Federation sign-out clean-up requests ("wsignoutcleanup1.0"), by deleting its session with the client. If the wreply parameter in the sign-out clean-up message is not set, the WSFAM returns an image of a green check mark to the STS that sent the message. This feature can be used by an STS as an acknowledgment that the RP has completed its sign-out.

The WSFAM exposes its functionality -- for example, its request processing pipeline -- through several task-specific methods. You can override these methods in derived classes to alter the behavior of the WSFAM.

To be used, the module must be added to the pipeline as in the following 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>

Once configured, the WSFederationAuthenticationModule raises events at various stages of processing an HTTP request. ASP.NET developers can handle these events in the global.asax file.

Constructors

Properties

Methods

Events

Applies to