SessionSecurityTokenHandler Class

Definition

public ref class SessionSecurityTokenHandler : System::IdentityModel::Tokens::SecurityTokenHandler

public class SessionSecurityTokenHandler : System.IdentityModel.Tokens.SecurityTokenHandler

type SessionSecurityTokenHandler = class
    inherit SecurityTokenHandler

Public Class SessionSecurityTokenHandler
Inherits SecurityTokenHandler

Inheritance

Object

SecurityTokenHandler

SessionSecurityTokenHandler

Derived

System.IdentityModel.Services.Tokens.MachineKeySessionSecurityTokenHandler

Examples

The following XML shows how to replace the default session security token handler in a token handler collection with an instance of the MachineKeySessionSecurityTokenHandler class in configuration.

<securityTokenHandlers>
  <remove type="System.IdentityModel.Tokens.SessionSecurityTokenHandler, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
  <add type="System.IdentityModel.Services.Tokens.MachineKeySessionSecurityTokenHandler, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
</securityTokenHandlers>

Remarks

The SessionSecurityTokenHandler class serializes, deserializes, and validates session tokens. Session tokens are tokens of type SessionSecurityToken. The SessionSecurityTokenHandler class serializes the tokens to and from cookie format. By default, the class serializes tokens into WS-Secure Conversation Feb2005 or WS-Secure Conversation 1.3 <wsc:SecurityContextToken> elements. Session tokens are used by the WSFederationAuthenticationModule (WSFAM) and the SessionAuthenticationModule (SAM) to store information about a session, this is primarily the ClaimsPrincipal associated with the authenticated user and the session start and expiration times.

In passive scenarios, the WSFederationAuthenticationModule calls into the SessionAuthenticationModule (SAM) from the authentication pipeline to create a session token from the ClaimsPrincipal that represents the authenticated user. The SAM uses its configured SessionSecurityTokenHandler to create the token and to serialize it into a cookie (and to deserialize the token from a cookie on subsequent requests). The SAM uses an instance of its configured CookieHandler class to write the cookie back to the HTTP Response. This cookie is then returned to the client and on subsequent requests the client can present the cookie rather than making a round trip back to the identity provider to re-obtain a security token. For more information about how sessions operate with WIF, see WIF Session Management.

If the session token is in reference mode, that is, its SessionSecurityToken.IsReferenceMode property is true, the session token handler only serializes properties of the session token that are needed to regenerate its key in the SessionSecurityTokenCache. In the default case, the SessionSecurityTokenCacheKey class is used to represent cache keys, and the token handler writes the SessionSecurityToken.ContextId and SessionSecurityToken.KeyGeneration properties of the token. If the session token is not in reference mode, that is, the SessionSecurityToken.IsReferenceMode property is false, then, in addition to the properties mentioned previously, the handler invokes the ApplyTransforms method on a byte array serialized from the token and stores the resulting value in the cookie as well. For more details about how the token is serialized, see the SessionSecurityTokenHandler.WriteToken(XmlWriter, SecurityToken) method.

The Transforms property gets the list of transforms that are applied to the session token in the ApplyTransforms method. All transforms derive from the CookieTransform class. In the default case the DeflateCookieTransform and the ProtectedDataCookieTransform are applied. The ProtectedDataCookieTransform uses the Data Protection API (DPAPI) to protect the cookie material. DPAPI uses a key that is specific to the computer on which it is running in its protection algorithms. For this reason, the default session token handler is not usable in Web farm scenarios because, in such scenarios, tokens written on one computer may need to be read on another computer. You can use many strategies to circumvent this issue. For example, you can:

• Replace the default SessionSecurityTokenHandler with the MachineKeySessionSecurityTokenHandler. The MachineKeySessionSecurityTokenHandler enables you to specify signing and encryption keys under the ASP.NET <machineKey> element in the configuration file.

• Provide a handler for the FederatedAuthentication.FederationConfigurationCreated event in the global.asax.cs file and replace the default session token handler with an instance of SessionSecurityTokenHandler that has a list of transforms that includes the RsaSignatureCookieTransform and the RsaEncryptionCookieTransform. You can create the new instance by invoking one of the constructors that takes a list of transforms.

• Derive a custom transform from the CookieTransform base class and use the method above to include it in the list of transforms to be applied.

• Derive a custom token handler from SessionSecurityTokenHandler and implement your own mechanism.

For more information about using sessions in Web farm scenarios, see WIF and Web Farms.

The SessionSecurityTokenHandler is included in the default token handler collection; however, you can replace it with a custom session token handler by first specifying a <remove> element under the <securityTokenHandlers> element to remove the default handler from the collection and then adding your custom token handler using the <add> element. By default, you can specify the default token lifetime by including the <sessionTokenRequirement> element under the <add> element. You can design a custom token handler to take custom configuration elements under the <add> element by overriding the LoadCustomConfiguration method to provide the logic to process them.

Constructors

Fields

Properties

Methods

Applies to

See also

• SessionSecurityTokenCache
• SessionSecurityToken
• MachineKeySessionSecurityTokenHandler
• CookieTransform
• <sessionTokenRequirement>
• WIF and Web Farms
• WIF Session Management