SessionAuthenticationModule Class

.NET Framework (current version)
 

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

Namespace:   System.IdentityModel.Services
Assembly:  System.IdentityModel.Services (in System.IdentityModel.Services.dll)

System.Object
  System.IdentityModel.Services.HttpModuleBase
    System.IdentityModel.Services.SessionAuthenticationModule

Public Class SessionAuthenticationModule
	Inherits HttpModuleBase

NameDescription
System_CAPS_pubmethodSessionAuthenticationModule()

Initializes a new instance of the SessionAuthenticationModule class.

NameDescription
System_CAPS_pubpropertyContextSessionSecurityToken

Gets the active SessionSecurityToken for the current HttpContext.

System_CAPS_pubpropertyCookieHandler

Gets the cookie handler that is used to read, write, and delete session cookies.

System_CAPS_pubpropertyFederationConfiguration

Gets or sets the FederationConfiguration object that is in effect for the current module.(Inherited from HttpModuleBase.)

System_CAPS_pubpropertyIsReferenceMode

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.

NameDescription
System_CAPS_pubmethodAuthenticateSessionSecurityToken(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.

System_CAPS_pubmethodContainsSessionTokenCookie(HttpCookieCollection)

Determines whether a session cookie is in the specified cookie collection.

System_CAPS_pubmethodCreateSessionSecurityToken(ClaimsPrincipal, String, DateTime, DateTime, Boolean)

Creates a SessionSecurityToken from the specified parameters by using the configured session token handler.

System_CAPS_pubmethodDeleteSessionTokenCookie()

Deletes the session cookie and removes it from the cache.

System_CAPS_pubmethodDispose()

Releases the resources (except memory) used by the current instance of the HttpModuleBase class.(Inherited from HttpModuleBase.)

System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodInit(HttpApplication)

Initializes the HTTP module.(Inherited from HttpModuleBase.)

System_CAPS_protmethodInitializeModule(HttpApplication)

Initializes the module and prepares it to handle events from the module's ASP.NET application object.(Overrides HttpModuleBase.InitializeModule(HttpApplication).)

System_CAPS_protmethodInitializePropertiesFromConfiguration()

Initializes the module properties based on definitions in the configuration file.(Overrides HttpModuleBase.InitializePropertiesFromConfiguration().)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethodOnAuthenticateRequest(Object, EventArgs)

Handles the HttpApplication.AuthenticateRequest event from the ASP.NET pipeline.

System_CAPS_protmethodOnPostAuthenticateRequest(Object, EventArgs)

Handles the HttpApplication.PostAuthenticateRequest event from the ASP.NET pipeline.

System_CAPS_protmethodOnSessionSecurityTokenCreated(SessionSecurityTokenCreatedEventArgs)

Raises the SessionSecurityTokenCreated event.

System_CAPS_protmethodOnSessionSecurityTokenReceived(SessionSecurityTokenReceivedEventArgs)
System_CAPS_protmethodOnSignedOut(EventArgs)

Raises the SignedOut event.

System_CAPS_protmethodOnSigningOut(SigningOutEventArgs)

Raises the SigningOut event.

System_CAPS_protmethodOnSignOutError(ErrorEventArgs)

Raises the SignOutError event.

System_CAPS_pubmethodReadSessionTokenFromCookie(Byte())

Reads a SessionSecurityToken from the specified session cookie.

System_CAPS_protmethodSetPrincipalFromSessionToken(SessionSecurityToken)

Sets the principal on the HttpContext and Thread to the principal that is contained in the specified session token.

System_CAPS_pubmethodSignOut()

Signs the current user out and raises the associated events.

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

System_CAPS_pubmethodTryReadSessionTokenFromCookie(SessionSecurityToken)

Attempts to read a SessionSecurityToken from a session cookie and returns a value that indicates whether the session cookie was successfully read.

System_CAPS_protmethodValidateSessionToken(SessionSecurityToken)

Validates the specified SessionSecurityToken and returns its identities.

System_CAPS_pubmethodWriteSessionTokenToCookie(SessionSecurityToken)

Writes the specified SessionSecurityToken to a session cookie.

NameDescription
System_CAPS_pubeventSessionSecurityTokenCreated

Occurs when a session security token has been created.

System_CAPS_pubeventSessionSecurityTokenReceived

Occurs when a session security token has been read from a cookie.

System_CAPS_pubeventSignedOut

Occurs after the user is signed out.

System_CAPS_pubeventSigningOut

Occurs before deleting the sign-in session.

System_CAPS_pubeventSignOutError

Occurs when there is an error during sign-out.

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.

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>

.NET Framework
Available since 4.5

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: