Token Handlers

[Starting with the .NET Framework 4.5, Windows Identity Foundation (WIF) has been fully integrated into the .NET Framework. The version of WIF addressed by this topic, WIF 3.5, is deprecated and should only be used when developing against the .NET Framework 3.5 SP1 or the .NET Framework 4. For more information about WIF in the .NET Framework 4.5, also known as WIF 4.5, see the Windows Identity Foundation documentation in the .NET Framework 4.5 Development Guide.]

A security token handler is responsible for creating, reading, writing, and validating tokens. A collection of token handlers is used to take over some of the responsibilities of the token manager used by Windows Communication Foundation (WCF). WIF plugs the security token handler collection into the WCF pipeline for you. A WIF token handler provides a single extensibility point for adding support for additional token types as well as customizing the handling of token types that WIF supports by default.

The following diagram shows how the token handler fits into processing a request:


A service token handler collection must contain the EncryptedSecurityTokenHandler in order to parse tokens with the EncryptedKey key identifier clause.

EncryptedKeyEncryptingCredentials represents a two-layer credentials object that describes an ephemeral symmetric key that is used to encrypt data, but the key itself is protected, or 'wrapped', with an asymmetric encryption token.

X509EncryptingCredentials represents a single-layer object that describes an asymmetric key. This is used as wrapping credentials on the EncryptedKeyEncryptingCredentials object.

Customers looking to set EncryptingCredentials should use X509EncryptingCredentials. The token issuance pipeline will convert this into an EncryptedKeyEncryptingCredentials on each request in CreateSecurityTokenDescriptor, generating a symmetric key per request.

For more information about token handlers and token handler collections, see Configuration.

Note that the token handler APIs do not require you to use XmlDictionaryWriter or XmlDictionaryReader; they will accept XmlWriter or XmlReader. However, it is recommended that you use XmlDictionaryWriter or XmlDictionaryReader.

The topics in this section provide more details on security token handlers: