Built-In 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.]
Built-In Security Token Handlers
WIF provides the following built-in token handlers:
KerberosSecurityTokenHandler
KerberosSecurityTokenHandler validates tokens of type KerberosReceiverSecurityToken. This token type, which is used by WCF during Kerberos authentication, wraps a Windows identity and is based on a Kerberos ticket that is received in a SOAP message. This token type is not used in SPNego or SSPI authentication.
This handler does not implement any other token handler methods, such as ReadToken or WriteToken. This is because, unlike other token types such as SAML and X.509, the KerberosReceiverSecurityToken has no wire-serializable form.
RsaSecurityTokenHandler
RsaSecurityTokenHandler handles tokens of type RsaSecurityToken, which is based on a key created with the RSA security algorithm.
X509SecurityTokenHandler
X509SecurityTokenHandler handles tokens of type X509SecurityToken, which is based on an X.509 certificate.
The X509SecurityTokenHandler also processes X.509 data security keys stored inside tokens.
Saml11SecurityTokenHandler
Saml11SecurityTokenHandler handles SAML 1.1 security tokens.
Saml2SecurityTokenHandler
Saml2SecurityTokenHandler handles SAML 2 security tokens.
MembershipUserNameSecurityTokenHandler and WindowsUserNameSecurityTokenHandler
MembershipUserNameSecurityTokenHandler and WindowsUserNameSecurityTokenHandler both derive from UserNameSecurityTokenHandler, and both handle tokens of type UsernameSecurityToken. These handlers are mutually exclusive and differ only in the way they handle tokens. MembershipUserNameSecurityTokenHandler allows the specification of a MembershipProvider to validate tokens. WindowsUserNameSecurityTokenHandler validates the token by mapping the user to a windows account. These two token handlers must not be combined in the same token handler collection.
WindowsSecurityToken
Finally, there is a token type that does not have a handler: The WindowsSecurityToken used by WCF. This token wraps a Windows identity. It is used when a Windows token is presented during transport-level authentication, such as over a net.tcp transport. It always appears in the bootstrap token collection.
You can extract the Windows identity from a WindowsSecurityToken and convert it to an IClaimsIdentity as follows:
IClaimsIdentity rehydratedIdentity = new WindowsClaimsIdentity(
(token as WindowsSecurityToken).WindowsIdentity.Token,
(token as WindowsSecurityToken).WindowsIdentity.AuthenticationType);
WIF also provides the following token handlers for token types that are not directly concerned with authentication:
EncryptedSecurityTokenHandler
EncryptedSecurityTokenHandler handles tokens of type EncryptedSecurityToken. This token type provides encryption for token types that do not natively support it. For example, a SAML 1.1 token does not know how to encrypt itself. So, to issue an encrypted SAML11 assertion, wrap a SAML security token with an EncryptedSecurityToken and provide appropriate EncryptingCredentials.
EncryptedSecurityTokenHandler invokes its containing collection in order to process a security token after decryption. When an EncryptedSecurityTokenHandler is added to a collection, the ContainingCollection property is automatically set to point to the parent collection. The decryption of a token is hence a two-stage process. The first stage is conversion from the raw encrypted form to an unencrypted form, and is handled by the EncryptedSecurityTokenHandler. Then the containing collection is invoked with the unencrypted token in order to further convert from the token XML to an in-memory SecurityToken object.
The EncryptedSecurityTokenHandler also processes encrypted keys stored inside tokens.
SessionSecurityTokenHandler
SessionSecurityTokenHandler handles tokens of type SessionSecurityToken. This token type contains claims for an authenticated user, so that the user does not have to re-authenticate with every request. For more information, see WS-Federated Authentication Module Overview.
Warning
When reserializing SAML bootstrap tokens (such as in an ActAs scenario) using multiple threads, you must synchronize your calls; otherwise, the tokens might become corrupted. For more information about ActAs, see Identity Delegation Scenario and Frequently Asked Questions.
How Windows Identity Foundation Uses Security Token Handlers to Issue Tokens
SecurityTokenService has an internal token creation pipeline, implemented in Issue that looks like this:
Call GetScope. This method retrieves the relying party information.
Call CreateSecurityTokenDescriptor. This method simply creates a SecurityTokenDescriptor based on the scope information from step 1.
Call GetSecurityTokenHandler. The parameter is the token type from the RequestSecurityToken that was passed to Issue.
Call GetIssuerName and add the issuer name (the STS’s name) to the token descriptor.
Call GetTokenLifetime and add the token lifetime to the token descriptor.
Call GetProofToken and add the proof token descriptor to the token descriptor.
Call GetOutputClaimsIdentity and add the collection of output subjects to the token descriptor.
Call CreateToken. This method is implemented by the Security Token Handler. The parameter is the security token descriptor that we’ve created.
Call GetResponse. This method gets the RequestSecurityTokenResponse.
Normally, when you develop an STS, you simply create a class that derives from SecurityTokenService and implement GetScope and GetOutputClaimsIdentity. If you want more control over token handling, you can override any of the methods listed here.