SessionSecurityTokenHandler Class

Reference

Definition

Namespace:: System.IdentityModel.Tokens

Assembly:: System.IdentityModel.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.

A SecurityTokenHandler that processes security tokens of type SessionSecurityToken.

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.

Note

The <securityTokenHandlers> configuration element can be used to specify a SessionSecurityTokenHandler that has the responsibility for securing the application's sessions. Developers should use caution when changing this configuration setting, as a misconfigured system could result in application compromise. For example, specifying a derived SessionSecurityTokenHandler and passing an empty Transforms (CookieTransform) collection to the base, would result in the users identity being serialized into a cookie that was not protected. This could allow an attacker to modify the identity and therefore change access privileges.

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

SessionSecurityTokenHandler()	Initializes a new instance of the SessionSecurityTokenHandler class that uses the default cookie transforms and token lifetime.
SessionSecurityTokenHandler(ReadOnlyCollection<CookieTransform>, TimeSpan)	Initializes a new instance of the SessionSecurityTokenHandler class that uses the specified cookie transforms and token lifetime.
SessionSecurityTokenHandler(ReadOnlyCollection<CookieTransform>)	Initializes a new instance of the SessionSecurityTokenHandler class that uses the specified cookie transforms.

Fields

DefaultCookieTransforms	A read only collection that contains the list of default transforms to be applied to cookies, the DeflateCookieTransform and the ProtectedDataCookieTransform.
DefaultLifetime	A constant that specifies the default lifetime for cookies, ten hours.

Properties

CanValidateToken	Gets a value that indicates whether this handler supports validation of tokens of type SessionSecurityToken.
CanWriteToken	Gets a value that indicates whether this handler can write tokens of type SessionSecurityToken.
Configuration	Gets or sets the SecurityTokenHandlerConfiguration object that provides configuration for the current instance. (Inherited from SecurityTokenHandler)
ContainingCollection	Gets the token handler collection that contains the current instance. (Inherited from SecurityTokenHandler)
CookieElementName	Gets the name for the cookie element.
CookieNamespace	Gets the namespace for the cookie element.
DefaultTokenLifetime	Gets the default token lifetime.
TokenLifetime	Gets or sets the token lifetime.
TokenType	Gets the type of the tokens that this handler processes.
Transforms	Gets the transforms that will be applied to the cookie.

Methods

ApplyTransforms(Byte[], Boolean)	Applies the transforms specified by the Transforms property to either encode or decode the specified cookie.
CanReadKeyIdentifierClause(XmlReader)	Returns a value that indicates whether the XML element referred to by the specified XML reader is a key identifier clause that can be deserialized by this instance. (Inherited from SecurityTokenHandler)
CanReadToken(String)	Returns a value that indicates whether the specified string can be deserialized as a token of the type processed by this instance. (Inherited from SecurityTokenHandler)
CanReadToken(XmlReader)	Returns a value that indicates whether the reader is positioned at a `<wsc:SecurityContextToken>` element.
CanWriteKeyIdentifierClause(SecurityKeyIdentifierClause)	Returns a value that indicates whether the specified key identifier clause can be serialized by this instance. (Inherited from SecurityTokenHandler)
CreateSecurityTokenReference(SecurityToken, Boolean)	When overridden in a derived class, creates the security token reference for tokens processed by that class. This method is typically called by a security token service (STS). (Inherited from SecurityTokenHandler)
CreateSessionSecurityToken(ClaimsPrincipal, String, String, DateTime, DateTime)	Creates a SessionSecurityToken based on the specified claims principal and time range during which the token is valid.
CreateToken(SecurityTokenDescriptor)	Creates a security token based on the specified token descriptor.
DetectReplayedToken(SecurityToken)	When overridden in a derived class, throws an exception if the specified token is detected as being replayed. (Inherited from SecurityTokenHandler)
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)
GetTokenTypeIdentifiers()	Gets the token type URIs for the token types that can be processed by this handler.
GetType()	Gets the Type of the current instance. (Inherited from Object)
LoadCustomConfiguration(XmlNodeList)	Loads custom configuration from XML.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ReadKeyIdentifierClause(XmlReader)	When overridden in a derived class, deserializes the XML referenced by the specified XML reader to a key identifier clause that references a token processed by the derived class. (Inherited from SecurityTokenHandler)
ReadToken(Byte[], SecurityTokenResolver)	Reads the SessionSecurityToken from a stream of bytes by using the specified token resolver.
ReadToken(String)	When overridden in a derived class, deserializes the specified string to a token of the type processed by the derived class. (Inherited from SecurityTokenHandler)
ReadToken(XmlReader, SecurityTokenResolver)	Reads the SessionSecurityToken using the specified XML reader and token resolver.
ReadToken(XmlReader)	Reads the SessionSecurityToken using the specified XML reader.
SetTransforms(IEnumerable<CookieTransform>)	Sets the transforms that will be applied to cookies.
ToString()	Returns a string that represents the current object. (Inherited from Object)
TraceTokenValidationFailure(SecurityToken, String)	Traces the failure event during the validation of security tokens when tracing is enabled. (Inherited from SecurityTokenHandler)
TraceTokenValidationSuccess(SecurityToken)	Traces the successful validation of security tokens event when tracing is enabled. (Inherited from SecurityTokenHandler)
ValidateSession(SessionSecurityToken)	Determines whether the session associated with the specified token is still valid. Validity is determined by checking the ValidFrom and ValidTo properties of the specified token. An exception is thrown if the session is no longer valid.
ValidateToken(SecurityToken)	Validates the specified token and returns its claims.
ValidateToken(SessionSecurityToken, String)	Validates the specified session token and returns its claims.
WriteKeyIdentifierClause(XmlWriter, SecurityKeyIdentifierClause)	When overridden in a derived class, serializes the specified key identifier clause to XML. The key identifier clause must be of the type supported by the derived class. (Inherited from SecurityTokenHandler)
WriteToken(SecurityToken)	When overridden in a derived class, serializes the specified security token to a string. The token must be of the type processed by the derived class. (Inherited from SecurityTokenHandler)
WriteToken(SessionSecurityToken)	Serializes the specified token into a byte array.
WriteToken(XmlWriter, SecurityToken)	Serializes the specified token by using the specified XML writer.

Applies to

Partajați prin