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:

  Copy Code 
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.

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

  1. Call GetScope. This method retrieves the relying party information.

  2. Call CreateSecurityTokenDescriptor. This method simply creates a SecurityTokenDescriptor based on the scope information from step 1.

  3. Call GetSecurityTokenHandler. The parameter is the token type from the RequestSecurityToken that was passed to Issue.

  4. Call GetIssuerName and add the issuer name (the STS’s name) to the token descriptor.

  5. Call GetTokenLifetime and add the token lifetime to the token descriptor.

  6. Call GetProofToken and add the proof token descriptor to the token descriptor.

  7. Call GetOutputClaimsIdentity and add the collection of output subjects to the token descriptor.

  8. Call CreateToken. This method is implemented by the Security Token Handler. The parameter is the security token descriptor that we’ve created.

  9. 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.