SessionAuthenticationModule Class

.NET Framework 4.6 and 4.5

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)

public class SessionAuthenticationModule : HttpModuleBase

The SessionAuthenticationModule type exposes the following members.

Public methodSessionAuthenticationModuleInitializes a new instance of the SessionAuthenticationModule class.

Public propertyContextSessionSecurityTokenGets the active SessionSecurityToken for the current HttpContext.
Public propertyCookieHandlerGets the cookie handler that is used to read, write, and delete session cookies.
Public propertyFederationConfigurationGets or sets the FederationConfiguration object that is in effect for the current module. (Inherited from HttpModuleBase.)
Public propertyIsReferenceModeGets 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.

Public methodAuthenticateSessionSecurityTokenAuthenticates 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.
Public methodContainsSessionTokenCookieDetermines whether a session cookie is in the specified cookie collection.
Public methodCreateSessionSecurityTokenCreates a SessionSecurityToken from the specified parameters by using the configured session token handler.
Public methodDeleteSessionTokenCookieDeletes the session cookie and removes it from the cache.
Public methodDisposeReleases the resources (except memory) used by the current instance of the HttpModuleBase class. (Inherited from HttpModuleBase.)
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodInitInitializes the HTTP module. (Inherited from HttpModuleBase.)
Protected methodInitializeModuleInitializes the module and prepares it to handle events from the module's ASP.NET application object. (Overrides HttpModuleBase.InitializeModule(HttpApplication).)
Protected methodInitializePropertiesFromConfigurationInitializes the module properties based on definitions in the configuration file. (Overrides HttpModuleBase.InitializePropertiesFromConfiguration().)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnAuthenticateRequestHandles the HttpApplication.AuthenticateRequest event from the ASP.NET pipeline.
Protected methodOnPostAuthenticateRequestHandles the HttpApplication.PostAuthenticateRequest event from the ASP.NET pipeline.
Protected methodOnSessionSecurityTokenCreatedRaises the SessionSecurityTokenCreated event.
Protected methodOnSessionSecurityTokenReceivedRaises the SessionSecurityTokenReceived event.
Protected methodOnSignedOutRaises the SignedOut event.
Protected methodOnSigningOutRaises the SigningOut event.
Protected methodOnSignOutErrorRaises the SignOutError event.
Public methodReadSessionTokenFromCookieReads a SessionSecurityToken from the specified session cookie.
Protected methodSetPrincipalFromSessionTokenSets the principal on the HttpContext and Thread to the principal that is contained in the specified session token.
Public methodSignOutSigns the current user out and raises the associated events.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodTryReadSessionTokenFromCookieAttempts to read a SessionSecurityToken from a session cookie and returns a value that indicates whether the session cookie was successfully read.
Protected methodValidateSessionTokenValidates the specified SessionSecurityToken and returns its identities.
Public methodWriteSessionTokenToCookieWrites the specified SessionSecurityToken to a session cookie.

Public eventSessionSecurityTokenCreatedOccurs when a session security token has been created.
Public eventSessionSecurityTokenReceivedOccurs when a session security token has been read from a cookie.
Public eventSignedOutOccurs after the user is signed out.
Public eventSigningOutOccurs before deleting the sign-in session.
Public eventSignOutErrorOccurs 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 

            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.

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

.NET Framework

Supported in: 4.6, 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.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
© 2015 Microsoft