MachineKeySessionSecurityTokenHandler Class

.NET Framework (current version)
 

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

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

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

type MachineKeySessionSecurityTokenHandler = 
    class
        inherit SessionSecurityTokenHandler
    end

NameDescription
System_CAPS_pubmethodMachineKeySessionSecurityTokenHandler()

Initializes a new instance of the MachineKeySessionSecurityTokenHandler class.

System_CAPS_pubmethodMachineKeySessionSecurityTokenHandler(TimeSpan)

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

NameDescription
System_CAPS_pubpropertyCanValidateToken

Gets a value that indicates whether this handler supports validation of tokens of type SessionSecurityToken.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubpropertyCanWriteToken

Gets a value that indicates whether this handler can write tokens of type SessionSecurityToken.(Inherited from SessionSecurityTokenHandler.)

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.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubpropertyCookieNamespace

Gets the namespace for the cookie element.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubpropertyTokenLifetime

Gets or sets the token lifetime.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubpropertyTokenType

Gets the type of the tokens that this handler processes.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubpropertyTransforms

Gets the transforms that will be applied to the cookie.(Inherited from SessionSecurityTokenHandler.)

NameDescription
System_CAPS_protmethodApplyTransforms(Byte[], Boolean)

Applies the transforms specified by the Transforms property to either encode or decode the specified cookie.(Inherited from SessionSecurityTokenHandler.)

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.(Inherited from SessionSecurityTokenHandler.)

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.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubmethodCreateToken(SecurityTokenDescriptor)

Creates a security token based on the specified token descriptor.(Inherited from SessionSecurityTokenHandler.)

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.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubmethodGetType()

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

System_CAPS_pubmethodLoadCustomConfiguration(XmlNodeList)

Loads custom configuration from XML.(Inherited from SessionSecurityTokenHandler.)

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(Byte[], SecurityTokenResolver)

Reads the SessionSecurityToken from a stream of bytes by using the specified token resolver.(Inherited from SessionSecurityTokenHandler.)

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.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubmethodReadToken(XmlReader, SecurityTokenResolver)

Reads the SessionSecurityToken using the specified XML reader and token resolver.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_protmethodSetTransforms(IEnumerable<CookieTransform>)

Sets the transforms that will be applied to cookies.(Inherited from SessionSecurityTokenHandler.)

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.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubmethodValidateToken(SecurityToken)

Validates the specified token and returns its claims.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubmethodValidateToken(SessionSecurityToken, String)

Validates the specified session token and returns its claims.(Inherited from SessionSecurityTokenHandler.)

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.(Inherited from SessionSecurityTokenHandler.)

System_CAPS_pubmethodWriteToken(XmlWriter, SecurityToken)

Serializes the specified token by using the specified XML writer.(Inherited from SessionSecurityTokenHandler.)

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