SessionAuthenticationModule Class

Definition

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

public class SessionAuthenticationModule : System.IdentityModel.Services.HttpModuleBase

type SessionAuthenticationModule = class
    inherit HttpModuleBase

Public Class SessionAuthenticationModule
Inherits HttpModuleBase

Inheritance

Object

HttpModuleBase

SessionAuthenticationModule

Examples

void Application_Start(object sender, EventArgs e)
{
    // Code that runs on application startup

    //SUBSCRIBE TO SAM EVENTS
    FederatedAuthentication.SessionAuthenticationModule.SessionSecurityTokenCreated += new EventHandler<SessionSecurityTokenCreatedEventArgs>(SessionAuthenticationModule_SessionSecurityTokenCreated);
    FederatedAuthentication.SessionAuthenticationModule.SessionSecurityTokenReceived += new EventHandler<SessionSecurityTokenReceivedEventArgs>(SessionAuthenticationModule_SessionSecurityTokenReceived);
    FederatedAuthentication.SessionAuthenticationModule.SigningOut += new EventHandler<SigningOutEventArgs>(SessionAuthenticationModule_SigningOut);
    FederatedAuthentication.SessionAuthenticationModule.SignedOut += new EventHandler(SessionAuthenticationModule_SignedOut);
    FederatedAuthentication.SessionAuthenticationModule.SignOutError += new EventHandler<ErrorEventArgs>(SessionAuthenticationModule_SignOutError);
}
void SessionAuthenticationModule_SignOutError(object sender, ErrorEventArgs e)
{
    System.Diagnostics.Trace.WriteLine("Handling SignOutError event");
}

void SessionAuthenticationModule_SignedOut(object sender, EventArgs e)
{
    System.Diagnostics.Trace.WriteLine("Handling SignedOut event");
}

void SessionAuthenticationModule_SigningOut(object sender, SigningOutEventArgs e)
{
    System.Diagnostics.Trace.WriteLine("Handling SigningOut event");
}

void SessionAuthenticationModule_SessionSecurityTokenReceived(object sender, SessionSecurityTokenReceivedEventArgs e)
{
    System.Diagnostics.Trace.WriteLine("Handling SessionSecurityTokenReceived event");
}

void SessionAuthenticationModule_SessionSecurityTokenCreated(object sender, SessionSecurityTokenCreatedEventArgs e)
{
    System.Diagnostics.Trace.WriteLine("Handling SessionSecurityTokenCreated event");
    //Store session on the server-side token cache instead writing the whole token to the cookie.
    //It may improve throughput but introduces server affinity that may affect scalability
    FederatedAuthentication.SessionAuthenticationModule.IsReferenceMode = true;
}

The following XML shows how to configure the SAM in the ASP.NET pipeline. Many other elements that are present in a typical configuration are omitted here for brevity.

<configuration>  
  <system.webServer>  
    <modules>  
      <!--WIF 4.5 modules -->  
      <add name="SessionAuthenticationModule" type="System.IdentityModel.Services.SessionAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>  
      <add name="WsFederationAuthenticationModule" type="System.IdentityModel.Services.WSFederationAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>  
    </modules>  
  </system.webServer>  
</configuration>  

Remarks

When present in the ASP.NET pipeline, the SessionAuthenticationModule (SAM) processes session cookies in WS-Federation scenarios. It uses the cookie handler specified by the CookieHandler property to read the raw session cookie from the HTTP request and write it to the HTTP response. It uses the SessionSecurityTokenHandler that is configured for an application to deserialize the raw session cookie into SessionSecurityToken objects. The session security token contains the claims (Claim) and principal (ClaimsPrincipal) associated with the entity for which the request is being served.

The SAM adds its OnAuthenticateRequest event handler to the HttpApplication.AuthenticateRequest event in the ASP.NET pipeline. This handler intercepts sign-in requests, and, if there is a session cookie, deserializes it into a session token, and sets the Thread.CurrentPrincipal and HttpContext.User properties to the claims principal contained in the session token. It invokes several of the other methods exposed by the SAM during this process.

The SignOut method can be invoked to sign the user out of a session (for example, in a SignOut.aspx.cs code-behind file).

The SAM exposes several events that provide access to its processing pipeline. The SessionSecurityTokenReceived and SessionSecurityTokenCreated events enable you to modify session tokens that are read from cookies or created during processing. Typically, this is done to add, remove, or transform claims in the token or to adjust its expiration time. The SigningOut, SignedOut, and SignOutError events provide hooks into the processing of sign-out requests. For many scenarios, simply adding handlers for these events, often to the global.asax.cs file, will be sufficient.

For more complicated scenarios, you can derive from SessionAuthenticationModule to implement a custom SAM. To this end, many of the methods that are invoked during OnAuthenticateRequest and SignOut are exposed so that you can provide custom behavior at specific stages of the session processing lifecycle.

You can add the SAM to the ASP.NET pipeline in a configuration file by adding it to the HTTP modules under either the <system.webServer> element for IIS version 7 and later or under the <system.web> element for versions prior to IIS 7. The cookie handler used by the SAM can be configured with the <cookieHandler> element.

Constructors

Properties

Methods

Events

Applies to