MachineKeySessionSecurityTokenHandler Class

.NET Framework 4.5

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

System.Object
  System.IdentityModel.Tokens.SecurityTokenHandler
    System.IdentityModel.Tokens.SessionSecurityTokenHandler
      System.IdentityModel.Services.Tokens.MachineKeySessionSecurityTokenHandler

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

public class MachineKeySessionSecurityTokenHandler : SessionSecurityTokenHandler

The MachineKeySessionSecurityTokenHandler type exposes the following members.

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

  NameDescription
Public propertyCanValidateTokenGets a value that indicates whether this handler supports validation of tokens of type SessionSecurityToken. (Inherited from SessionSecurityTokenHandler.)
Public propertyCanWriteTokenGets a value that indicates whether this handler can write tokens of type SessionSecurityToken. (Inherited from SessionSecurityTokenHandler.)
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. (Inherited from SessionSecurityTokenHandler.)
Public propertyCookieNamespaceGets the namespace for the cookie element. (Inherited from SessionSecurityTokenHandler.)
Public propertyTokenLifetimeGets or sets the token lifetime. (Inherited from SessionSecurityTokenHandler.)
Public propertyTokenTypeGets the type of the tokens that this handler processes. (Inherited from SessionSecurityTokenHandler.)
Public propertyTransformsGets the transforms that will be applied to the cookie. (Inherited from SessionSecurityTokenHandler.)
Top

  NameDescription
Protected methodApplyTransformsApplies the transforms specified by the Transforms property to either encode or decode the specified cookie. (Inherited from SessionSecurityTokenHandler.)
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. (Inherited from SessionSecurityTokenHandler.)
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. (Inherited from SessionSecurityTokenHandler.)
Public methodCreateTokenCreates a security token based on the specified token descriptor. (Inherited from SessionSecurityTokenHandler.)
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. (Inherited from SessionSecurityTokenHandler.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodLoadCustomConfigurationLoads custom configuration from XML. (Inherited from SessionSecurityTokenHandler.)
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. (Inherited from SessionSecurityTokenHandler.)
Public methodReadToken(Byte[], SecurityTokenResolver)Reads the SessionSecurityToken from a stream of bytes by using the specified token resolver. (Inherited from SessionSecurityTokenHandler.)
Public methodReadToken(XmlReader, SecurityTokenResolver)Reads the SessionSecurityToken using the specified XML reader and token resolver. (Inherited from SessionSecurityTokenHandler.)
Protected methodSetTransformsSets the transforms that will be applied to cookies. (Inherited from SessionSecurityTokenHandler.)
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. (Inherited from SessionSecurityTokenHandler.)
Public methodValidateToken(SecurityToken)Validates the specified token and returns its claims. (Inherited from SessionSecurityTokenHandler.)
Public methodValidateToken(SessionSecurityToken, String)Validates the specified session token and returns its claims. (Inherited from SessionSecurityTokenHandler.)
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. (Inherited from SessionSecurityTokenHandler.)
Public methodWriteToken(XmlWriter, SecurityToken)Serializes the specified token by using the specified XML writer. (Inherited from SessionSecurityTokenHandler.)
Top

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.

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>

.NET Framework

Supported in: 4.5.2, 4.5.1, 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.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft