MachineKeySessionSecurityTokenHandler Class

Reference

Definition

Namespace:: System.IdentityModel.Services.Tokens

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

Processes session tokens by using signing and encryption keys specified in the ASP.NET <machineKey> element in a configuration file.

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

public class MachineKeySessionSecurityTokenHandler : System.IdentityModel.Tokens.SessionSecurityTokenHandler

type MachineKeySessionSecurityTokenHandler = class
    inherit SessionSecurityTokenHandler

Public Class MachineKeySessionSecurityTokenHandler
Inherits SessionSecurityTokenHandler

Inheritance: Object

SecurityTokenHandler

SessionSecurityTokenHandler
MachineKeySessionSecurityTokenHandler

Examples

The following XML shows how to use the ASP.NET <machineKey> element in configuration to explicitly specify signing and encryption keys. The <machineKey> element is specified under the <system.web> element in a configuration file.

<machineKey compatibilityMode="Framework45" decryptionKey="CC510D … 8925E6" validationKey="BEAC8 … 6A4B1DE" />

The following XML shows how to add the MachineKeySessionSecurityTokenHandler to a token handler collection. The default SessionSecurityTokenHandler is first removed from the collection. Token handlers are configured under the <securityTokenHandlers> element.

<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

By default, the SessionSecurityTokenHandler class uses the ProtectedDataCookieTransform class, which uses the Data Protection API (DPAPI), to protect the session token. The DPAPI provides protection by using the user or machine credentials and stores the key data in the user profile. This means that a session token signed and encrypted on one computer cannot be validated or decrypted on a different computer.

By contrast, the MachineKeySessionSecurityTokenHandler class uses the MachineKeyTransform class, which protects the session cookie data by using the cryptographic material specified in the <machineKey> element in the configuration file. This means that the same keys (and session tokens) can be used across multiple computers. This is particularly important when an application is deployed in a web farm. For more information about how to use Windows Identity Foundation to protect applications that are deployed in a web farm, see WIF and Web Farms.

Configure the application to use the MachineKeySessionSecurityTokenHandler by adding it to the token handler collection. You must first remove the SessionSecurityTokenHandler (or any handler derived from the SessionSecurityTokenHandler class) from the token handler collection if such a handler is present. This is because MachineKeySessionSecurityTokenHandler derives from SessionSecurityTokenHandler and a token handler collection cannot contain multiple handlers of any given type.

Constructors

MachineKeySessionSecurityTokenHandler()	Initializes a new instance of the MachineKeySessionSecurityTokenHandler class.
MachineKeySessionSecurityTokenHandler(TimeSpan)	Initializes a new instance of the MachineKeySessionSecurityTokenHandler class that has the specified default token lifetime.

Properties

CanValidateToken	Gets a value that indicates whether this handler supports validation of tokens of type SessionSecurityToken. (Inherited from SessionSecurityTokenHandler)
CanWriteToken	Gets a value that indicates whether this handler can write tokens of type SessionSecurityToken. (Inherited from SessionSecurityTokenHandler)
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. (Inherited from SessionSecurityTokenHandler)
CookieNamespace	Gets the namespace for the cookie element. (Inherited from SessionSecurityTokenHandler)
TokenLifetime	Gets or sets the token lifetime. (Inherited from SessionSecurityTokenHandler)
TokenType	Gets the type of the tokens that this handler processes. (Inherited from SessionSecurityTokenHandler)
Transforms	Gets the transforms that will be applied to the cookie. (Inherited from SessionSecurityTokenHandler)

Methods

ApplyTransforms(Byte[], Boolean)	Applies the transforms specified by the Transforms property to either encode or decode the specified cookie. (Inherited from SessionSecurityTokenHandler)
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. (Inherited from SessionSecurityTokenHandler)
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. (Inherited from SessionSecurityTokenHandler)
CreateToken(SecurityTokenDescriptor)	Creates a security token based on the specified token descriptor. (Inherited from SessionSecurityTokenHandler)
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. (Inherited from SessionSecurityTokenHandler)
GetType()	Gets the Type of the current instance. (Inherited from Object)
LoadCustomConfiguration(XmlNodeList)	Loads custom configuration from XML. (Inherited from SessionSecurityTokenHandler)
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. (Inherited from SessionSecurityTokenHandler)
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)	Reads the SessionSecurityToken using the specified XML reader. (Inherited from SessionSecurityTokenHandler)
ReadToken(XmlReader, SecurityTokenResolver)	Reads the SessionSecurityToken using the specified XML reader and token resolver. (Inherited from SessionSecurityTokenHandler)
SetTransforms(IEnumerable<CookieTransform>)	Sets the transforms that will be applied to cookies. (Inherited from SessionSecurityTokenHandler)
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. (Inherited from SessionSecurityTokenHandler)
ValidateToken(SecurityToken)	Validates the specified token and returns its claims. (Inherited from SessionSecurityTokenHandler)
ValidateToken(SessionSecurityToken, String)	Validates the specified session token and returns its claims. (Inherited from SessionSecurityTokenHandler)
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. (Inherited from SessionSecurityTokenHandler)
WriteToken(XmlWriter, SecurityToken)	Serializes the specified token by using the specified XML writer. (Inherited from SessionSecurityTokenHandler)

Applies to