The workhorse of WIF are security token handler. Again token handler can be use independently of the WIF configuration system – or together.

The “stand-alone” use case
You can simply new up a token handler (e.g. the SAML 1.1 handler) in an arbitrary application.

var saml11Handler = new Saml11SecurityTokenHandler();

But a token handler needs more information to do its work (issuer name registry, audience URIs, certificate validation etc.). This information is all encapsulated in the SecurityTokenHandlerConfiguration class. You can reach into that class from the token handler’s Configuration property. Configuration is null by default and must be newed up and set manually.

Handler collections
Another option is to group a bunch of token handlers into a collection. This is useful when you have to deal with a number of in/output token types or need to chain token handlers (e.g. for encryption or compression). Collections also allow to share token handler configuration across contained handlers.

When you new up a SecurityTokenHandlerCollection you have the choice of passing in a SecurityTokenHandlerConfiguration instance, or you use a default configuration (not sure if these values are documented – use reflector ;). When you add a handler to a collection, the collection checks if the handler already has some configuration set (by checking if Configuration is not null). If this is not the case, then handler inherits the collection configuration.

var samlHandlers = new SecurityTokenHandlerCollection(new SecurityTokenHandler[]
    {
        saml11Handler,
        new Saml2SecurityTokenHandler()
    });

Another way to new up a handler collection is to use the static CreateDefaultSecurityTokenHandlerCollection method on the collection. This creates a collection with all default token handlers shipping with WIF. Again you have the option to pass in a configuration object.

Using configuration
Token handler configuration is typically an ideal candidate for configuration files. When you want to support that, you have two choices. Either copy the values from configuration, or use the configuration system to create and configure the handler.

Copying from configuration can be handy sometimes. To do that use the approach shown in my previous post to load the service configuration manually.

The WIF security token handler configuration section also has the concept of named handler collections. There is always a default token handler collection, but you can have additional ones – each with their own configuration, e.g.:

<securityTokenHandlers>
  <!– default token handlers – inherit global configuration settings –>
 
  <securityTokenHandlerConfiguration>
    <!– override with local configuration –>
   
    <audienceUris>
      <add value=“http://bar“ />
    </audienceUris>
  </securityTokenHandlerConfiguration>
</securityTokenHandlers>

<securityTokenHandlers name=“AccessToken“>
  <!– named token handler collection – inherit global configuration settings –>
  <securityTokenHandlerConfiguration>
    <!– override with local configuration –>
   
    <audienceUris mode=“Always“>
      <add value=“http://custom/*“ />
    </audienceUris>
    <tokenReplayDetection enabled=“true“ />
   
    <certificateValidation>
      <certificateValidator type=“AccessCertValidation, …“/>
    </certificateValidation>
  </securityTokenHandlerConfiguration>

  <clear />
  <add type=“AccessSecurityTokenHandler, …“ />
  <add type=“CompressedSecurityTokenHandler, …“ />

</securityTokenHandlers>

Programmatically, you can get to the standard token handler collection using the SecurityTokenHandlers property on ServiceConfiguration.

To get to the named token handlers, you use the SecurityTokenHandlerCollectionManager, e.g. like this:

var accessHandlers = config.SecurityTokenHandlerCollectionManager[“AccessToken”];

So as a rule of thumb: when you new up handlers or collections yourself, you are responsible for programmatic configuration. When you use ServiceConfiguration, the config file settings are applied automatically.