SessionAuthenticationModule Class

Reference

Definition

Namespace:: System.IdentityModel.Services

Assembly:: System.IdentityModel.Services.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Implements an ASP.NET module that processes session cookies in WS-Federation scenarios.

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

SessionAuthenticationModule()

Initializes a new instance of the SessionAuthenticationModule class.

Properties

ContextSessionSecurityToken	Gets the active SessionSecurityToken for the current HttpContext.
CookieHandler	Gets the cookie handler that is used to read, write, and delete session cookies.
FederationConfiguration	Gets or sets the FederationConfiguration object that is in effect for the current module. (Inherited from HttpModuleBase)
IsReferenceMode	Gets or sets a value that specifies whether the session information (claim values, etc.) should be stored in the session cookie or whether the session content should be stored on the server side, using the cookie to store just a reference.

Methods

AuthenticateSessionSecurityToken(SessionSecurityToken, Boolean)	Authenticates the incoming request by validating the incoming session token. Upon successful validation, it updates the current HTTP context and thread principal with the specified SessionSecurityToken.
ContainsSessionTokenCookie(HttpCookieCollection)	Determines whether a session cookie is in the specified cookie collection.
CreateSessionSecurityToken(ClaimsPrincipal, String, DateTime, DateTime, Boolean)	Creates a SessionSecurityToken from the specified parameters by using the configured session token handler.
DeleteSessionTokenCookie()	Deletes the session cookie and removes it from the cache.
Dispose()	Releases the resources (except memory) used by the current instance of the HttpModuleBase class. (Inherited from HttpModuleBase)
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
Init(HttpApplication)	Initializes the HTTP module. (Inherited from HttpModuleBase)
InitializeModule(HttpApplication)	Initializes the module and prepares it to handle events from the module's ASP.NET application object.
InitializePropertiesFromConfiguration()	Initializes the module properties based on definitions in the configuration file.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
OnAuthenticateRequest(Object, EventArgs)	Handles the AuthenticateRequest event from the ASP.NET pipeline.
OnPostAuthenticateRequest(Object, EventArgs)	Handles the PostAuthenticateRequest event from the ASP.NET pipeline.
OnSessionSecurityTokenCreated(SessionSecurityTokenCreatedEventArgs)	Raises the SessionSecurityTokenCreated event.
OnSessionSecurityTokenReceived(SessionSecurityTokenReceivedEventArgs)	Raises the SessionSecurityTokenReceived event.
OnSignedOut(EventArgs)	Raises the SignedOut event.
OnSigningOut(SigningOutEventArgs)	Raises the SigningOut event.
OnSignOutError(ErrorEventArgs)	Raises the SignOutError event.
ReadSessionTokenFromCookie(Byte[])	Reads a SessionSecurityToken from the specified session cookie.
SetPrincipalFromSessionToken(SessionSecurityToken)	Sets the principal on the HttpContext and Thread to the principal that is contained in the specified session token.
SignOut()	Signs the current user out and raises the associated events.
ToString()	Returns a string that represents the current object. (Inherited from Object)
TryReadSessionTokenFromCookie(SessionSecurityToken)	Attempts to read a SessionSecurityToken from a session cookie and returns a value that indicates whether the session cookie was successfully read.
ValidateSessionToken(SessionSecurityToken)	Validates the specified SessionSecurityToken and returns its identities.
WriteSessionTokenToCookie(SessionSecurityToken)	Writes the specified SessionSecurityToken to a session cookie.

Events

SessionSecurityTokenCreated	Occurs when a session security token has been created.
SessionSecurityTokenReceived	Occurs when a session security token has been read from a cookie.
SignedOut	Occurs after the user is signed out.
SigningOut	Occurs before deleting the sign-in session.
SignOutError	Occurs when there is an error during sign-out.

Applies to

Jaa