SessionSecurityTokenHandler Class

.NET Framework (current version)
 

A SecurityTokenHandler that processes security tokens of type SessionSecurityToken.

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


public ref class SessionSecurityTokenHandler : SecurityTokenHandler

NameDescription
System_CAPS_pubmethodSessionSecurityTokenHandler()

Initializes a new instance of the SessionSecurityTokenHandler class that uses the default cookie transforms and token lifetime.

System_CAPS_pubmethodSessionSecurityTokenHandler(ReadOnlyCollection<CookieTransform^>^)

Initializes a new instance of the SessionSecurityTokenHandler class that uses the specified cookie transforms.

System_CAPS_pubmethodSessionSecurityTokenHandler(ReadOnlyCollection<CookieTransform^>^, TimeSpan)

Initializes a new instance of the SessionSecurityTokenHandler class that uses the specified cookie transforms and token lifetime.

NameDescription
System_CAPS_pubpropertyCanValidateToken

Gets a value that indicates whether this handler supports validation of tokens of type SessionSecurityToken.(Overrides SecurityTokenHandler::CanValidateToken.)

System_CAPS_pubpropertyCanWriteToken

Gets a value that indicates whether this handler can write tokens of type SessionSecurityToken.(Overrides SecurityTokenHandler::CanWriteToken.)

System_CAPS_pubpropertyConfiguration

Gets or sets the SecurityTokenHandlerConfiguration object that provides configuration for the current instance.(Inherited from SecurityTokenHandler.)

System_CAPS_pubpropertyContainingCollection

Gets the token handler collection that contains the current instance.(Inherited from SecurityTokenHandler.)

System_CAPS_pubpropertyCookieElementName

Gets the name for the cookie element.

System_CAPS_pubpropertyCookieNamespace

Gets the namespace for the cookie element.

System_CAPS_pubpropertySystem_CAPS_staticDefaultTokenLifetime

Gets the default token lifetime.

System_CAPS_pubpropertyTokenLifetime

Gets or sets the token lifetime.

System_CAPS_pubpropertyTokenType

Gets the type of the tokens that this handler processes.(Overrides SecurityTokenHandler::TokenType.)

System_CAPS_pubpropertyTransforms

Gets the transforms that will be applied to the cookie.

NameDescription
System_CAPS_protmethodApplyTransforms(array<Byte>^, Boolean)

Applies the transforms specified by the Transforms property to either encode or decode the specified cookie.

System_CAPS_pubmethodCanReadKeyIdentifierClause(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.)

System_CAPS_pubmethodCanReadToken(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.)

System_CAPS_pubmethodCanReadToken(XmlReader^)

Returns a value that indicates whether the reader is positioned at a <wsc:SecurityContextToken> element.(Overrides SecurityTokenHandler::CanReadToken(XmlReader^).)

System_CAPS_pubmethodCanWriteKeyIdentifierClause(SecurityKeyIdentifierClause^)

Returns a value that indicates whether the specified key identifier clause can be serialized by this instance.(Inherited from SecurityTokenHandler.)

System_CAPS_pubmethodCreateSecurityTokenReference(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.)

System_CAPS_pubmethodCreateSessionSecurityToken(ClaimsPrincipal^, String^, String^, DateTime, DateTime)

Creates a SessionSecurityToken based on the specified claims principal and time range during which the token is valid.

System_CAPS_pubmethodCreateToken(SecurityTokenDescriptor^)

Creates a security token based on the specified token descriptor.(Overrides SecurityTokenHandler::CreateToken(SecurityTokenDescriptor^).)

System_CAPS_protmethodDetectReplayedToken(SecurityToken^)

When overridden in a derived class, throws an exception if the specified token is detected as being replayed.(Inherited from SecurityTokenHandler.)

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_pubmethodGetTokenTypeIdentifiers()

Gets the token type URIs for the token types that can be processed by this handler.(Overrides SecurityTokenHandler::GetTokenTypeIdentifiers().)

System_CAPS_pubmethodGetType()

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

System_CAPS_pubmethodLoadCustomConfiguration(XmlNodeList^)

Loads custom configuration from XML.(Overrides SecurityTokenHandler::LoadCustomConfiguration(XmlNodeList^).)

System_CAPS_protmethodMemberwiseClone()

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

System_CAPS_pubmethodReadKeyIdentifierClause(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.)

System_CAPS_pubmethodReadToken(array<Byte>^, SecurityTokenResolver^)

Reads the SessionSecurityToken from a stream of bytes by using the specified token resolver.

System_CAPS_pubmethodReadToken(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.)

System_CAPS_pubmethodReadToken(XmlReader^)

Reads the SessionSecurityToken using the specified XML reader.(Overrides SecurityTokenHandler::ReadToken(XmlReader^).)

System_CAPS_pubmethodReadToken(XmlReader^, SecurityTokenResolver^)

Reads the SessionSecurityToken using the specified XML reader and token resolver.(Overrides SecurityTokenHandler::ReadToken(XmlReader^, SecurityTokenResolver^).)

System_CAPS_protmethodSetTransforms(IEnumerable<CookieTransform^>^)

Sets the transforms that will be applied to cookies.

System_CAPS_pubmethodToString()

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

System_CAPS_protmethodTraceTokenValidationFailure(SecurityToken^, String^)

Traces the failure event during the validation of security tokens when tracing is enabled.(Inherited from SecurityTokenHandler.)

System_CAPS_protmethodTraceTokenValidationSuccess(SecurityToken^)

Traces the successful validation of security tokens event when tracing is enabled.(Inherited from SecurityTokenHandler.)

System_CAPS_protmethodValidateSession(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.

System_CAPS_pubmethodValidateToken(SecurityToken^)

Validates the specified token and returns its claims.(Overrides SecurityTokenHandler::ValidateToken(SecurityToken^).)

System_CAPS_pubmethodValidateToken(SessionSecurityToken^, String^)

Validates the specified session token and returns its claims.

System_CAPS_pubmethodWriteKeyIdentifierClause(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.)

System_CAPS_pubmethodWriteToken(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.)

System_CAPS_pubmethodWriteToken(SessionSecurityToken^)

Serializes the specified token into a byte array.

System_CAPS_pubmethodWriteToken(XmlWriter^, SecurityToken^)

Serializes the specified token by using the specified XML writer.(Overrides SecurityTokenHandler::WriteToken(XmlWriter^, SecurityToken^).)

NameDescription
System_CAPS_pubfieldSystem_CAPS_staticDefaultCookieTransforms

A read only collection that contains the list of default transforms to be applied to cookies, the DeflateCookieTransform and the ProtectedDataCookieTransform.

System_CAPS_pubfieldSystem_CAPS_staticDefaultLifetime

A constant that specifies the default lifetime for cookies, ten hours.

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.

System_CAPS_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 HYPERLINK "http://msdn.microsoft.com/en-us/library/hh193426%28v=vs.110%29.aspx" \t "_blank" 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> 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.

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
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: