Export (0) Print
Expand All

SessionSecurityTokenHandler Class

.NET Framework 4.5

A SecurityTokenHandler that processes security tokens of type SessionSecurityToken.

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

public class SessionSecurityTokenHandler : SecurityTokenHandler

The SessionSecurityTokenHandler type exposes the following members.

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

  NameDescription
Public propertyCanValidateTokenGets a value that indicates whether this handler supports validation of tokens of type SessionSecurityToken. (Overrides SecurityTokenHandler.CanValidateToken.)
Public propertyCanWriteTokenGets a value that indicates whether this handler can write tokens of type SessionSecurityToken. (Overrides SecurityTokenHandler.CanWriteToken.)
Public propertyConfigurationGets or sets the SecurityTokenHandlerConfiguration object that provides configuration for the current instance. (Inherited from SecurityTokenHandler.)
Public propertyContainingCollectionGets the token handler collection that contains the current instance. (Inherited from SecurityTokenHandler.)
Public propertyCookieElementNameGets the name for the cookie element.
Public propertyCookieNamespaceGets the namespace for the cookie element.
Public propertyStatic memberDefaultTokenLifetimeGets the default token lifetime.
Public propertyTokenLifetimeGets or sets the token lifetime.
Public propertyTokenTypeGets the type of the tokens that this handler processes. (Overrides SecurityTokenHandler.TokenType.)
Public propertyTransformsGets the transforms that will be applied to the cookie.
Top

  NameDescription
Protected methodApplyTransformsApplies the transforms specified by the Transforms property to either encode or decode the specified cookie.
Public methodCanReadKeyIdentifierClauseReturns 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.)
Public methodCanReadToken(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.)
Public methodCanReadToken(XmlReader)Returns a value that indicates whether the reader is positioned at a <wsc:SecurityContextToken> element. (Overrides SecurityTokenHandler.CanReadToken(XmlReader).)
Public methodCanWriteKeyIdentifierClauseReturns a value that indicates whether the specified key identifier clause can be serialized by this instance. (Inherited from SecurityTokenHandler.)
Public methodCreateSecurityTokenReferenceWhen 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.)
Public methodCreateSessionSecurityTokenCreates a SessionSecurityToken based on the specified claims principal and time range during which the token is valid.
Public methodCreateTokenCreates a security token based on the specified token descriptor. (Overrides SecurityTokenHandler.CreateToken(SecurityTokenDescriptor).)
Protected methodDetectReplayedTokenWhen overridden in a derived class, throws an exception if the specified token is detected as being replayed. (Inherited from SecurityTokenHandler.)
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 methodGetTokenTypeIdentifiersGets the token type URIs for the token types that can be processed by this handler. (Overrides SecurityTokenHandler.GetTokenTypeIdentifiers().)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodLoadCustomConfigurationLoads custom configuration from XML. (Overrides SecurityTokenHandler.LoadCustomConfiguration(XmlNodeList).)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodReadKeyIdentifierClauseWhen 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.)
Public methodReadToken(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.)
Public methodReadToken(XmlReader)Reads the SessionSecurityToken using the specified XML reader. (Overrides SecurityTokenHandler.ReadToken(XmlReader).)
Public methodReadToken(Byte[], SecurityTokenResolver)Reads the SessionSecurityToken from a stream of bytes by using the specified token resolver.
Public methodReadToken(XmlReader, SecurityTokenResolver)Reads the SessionSecurityToken using the specified XML reader and token resolver. (Overrides SecurityTokenHandler.ReadToken(XmlReader, SecurityTokenResolver).)
Protected methodSetTransformsSets the transforms that will be applied to cookies.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Protected methodTraceTokenValidationFailureTraces the failure event during the validation of security tokens when tracing is enabled. (Inherited from SecurityTokenHandler.)
Protected methodTraceTokenValidationSuccessTraces the successful validation of security tokens event when tracing is enabled. (Inherited from SecurityTokenHandler.)
Protected methodValidateSessionDetermines 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.
Public methodValidateToken(SecurityToken)Validates the specified token and returns its claims. (Overrides SecurityTokenHandler.ValidateToken(SecurityToken).)
Public methodValidateToken(SessionSecurityToken, String)Validates the specified session token and returns its claims.
Public methodWriteKeyIdentifierClauseWhen 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.)
Public methodWriteToken(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.)
Public methodWriteToken(SessionSecurityToken)Serializes the specified token into a byte array.
Public methodWriteToken(XmlWriter, SecurityToken)Serializes the specified token by using the specified XML writer. (Overrides SecurityTokenHandler.WriteToken(XmlWriter, SecurityToken).)
Top

  NameDescription
Public fieldStatic memberDefaultCookieTransformsA read only collection that contains the list of default transforms to be applied to cookies, the DeflateCookieTransform and the ProtectedDataCookieTransform.
Public fieldStatic memberDefaultLifetimeA constant that specifies the default lifetime for cookies, ten hours.
Top

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.

NoteNote

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:

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> [securityTokenHandlers] element under the <securityTokenHandlers> element to remove the default handler from the collection and then adding your custom token handler using the <add> [securityTokenHandlers] 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.

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>

.NET Framework

Supported in: 4.6, 4.5

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

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