Token Handler Configuration

[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.]

This topic talks about how to configure security token handlers for your relying party application or security token service (STS).

You can configure the security token handlers through the application’s configuration file, or programmatically create a configuration object and set that as a property of security token handlers.

It is recommended that you do not set the Configuration property on an individual token handler. Rather, you should set the Configuration property on the token handler collection. If you must set the Configuration property on an individual token handler, you should do so after you add the handler to the collection. This is because, when you add a token handler to a collection, the handler’s Configuration is set to the configuration of the collection, and the handler’s ContainingCollection property is set to the collection instance. Also, removing a token handler from a collection causes these properties to be nulled out.

In addition, you should not add a token handler to more than one collection. This will cause an error because of the behavior described previously. If multiple token handlers with different configurations are required in the same collection, you should add these handlers to the collection first, then create new SecurityTokenHandlerConfiguration instances and assign them to each handler individually to ensure that state is not accidentally shared.

You can also set the Configuration property on an individual token handler if you use it without a collection.

The security token handler configuration can also be set in the application’s configuration file. The following is an example configuration:

<microsoft.identityModel>
<!-- This is equivalent to the ServiceConfiguration class. -->
<service>
<!-- This is equivalent to the default token handler collection,
ServiceConfiguration.SecurityTokenHandlers -->
    <securityTokenHandlers>
<!-- This is the collection-level configuration, not the handler-level configuration.
Note that you can programmatically configure an individual token handler as described
previously, though that is not recommended. However, you cannot do so in a configuration file.
-->
      <securityTokenHandlerConfiguration>
<!-- IssuerNameRegistry contains the trusted issuers list.-->
        <issuerNameRegistry />
<!-- ServiceTokenResolver is for resolving the encryption certificates while decrypting the token.-->
        <serviceTokenResolver />
<!-- IssuerTokenResolver is for resolving the signing certificates while verifying the signature of the token issued by an STS. -->
        <issuerTokenResolver />
<!-- AudienceUris contains the URIs where the application expects the security tokens to be delivered. -->
        <audienceUris mode="Always" />
      </securityTokenHandlerConfiguration>
    </securityTokenHandlers>
<!-- This is equivalent to looking up the ActAs token handler collection in the
token handler collection manager using either of the following:
ServiceConfiguration.SecurityTokenHandlerCollectionManager["ActAs"]
ServiceConfiguration.SecurityTokenHandlerCollectionManager[
    SecurityTokenHandlerCollectionManager.Usage.ActAs];
-->
    <securityTokenHandlers name="ActAs"> 
    </securityTokenHandlers>
    <issuerNameRegistry ... />
    <serviceTokenResolver ... />
  </service>
<!-- This is equivalent to creating a new ServiceConfiguration as follows:
new ServiceConfiguration("CustomService");
-->
  <service name="CustomService">
</service>
</microsoft.identityModel>

Configuring Revocation and Validation Settings for X509CertificateTokenHandler

The following code shows how to programmatically configure revocation and validation settings for the X509CertificateTokenHandler.

using Microsoft.IdentityModel.Tokens;
using Microsoft.IdentityModel.Configuration;
using System.IdentityModel.Selectors;
using System.Security.Cryptography.X509Certificates;
using System.ServiceModel.Security;

class Sample
{
    public static void ConfigureCustomValidator()
    {
        // 1a. Configure a service configuration object (custom)
        ServiceConfiguration serviceConfig = new ServiceConfiguration();
        serviceConfig.CertificateValidationMode = X509CertificateValidationMode.Custom;
        serviceConfig.CertificateValidator = new CustomX509Validator();

        // 1b. Configure an individual X509SecurityTokenHandler (custom)
        X509CertificateValidator customValidator = new CustomX509Validator();
        X509SecurityTokenHandler x509Handler = new X509SecurityTokenHandler(customValidator);
    }

    public static void DisableRevocationMode()
    {
        // 2a. Configure a service configuration object (change revocation mode)
        ServiceConfiguration serviceConfig = new ServiceConfiguration();
        serviceConfig.RevocationMode = X509RevocationMode.NoCheck;
        serviceConfig.TrustedStoreLocation = StoreLocation.LocalMachine;
        serviceConfig.CertificateValidationMode = X509CertificateValidationMode.ChainTrust;

        // 2b. Configure an individual X509SecurityTokenHandler (change revocation mode)
        X509SecurityTokenHandler x509Handler = new X509SecurityTokenHandler();
        X509ChainPolicy chainPolicy = new X509ChainPolicy();
        chainPolicy.RevocationMode = X509RevocationMode.NoCheck;
        x509Handler.CertificateValidator = X509CertificateValidator.CreateChainTrustValidator(true, chainPolicy);
    }

    class CustomX509Validator : X509CertificateValidator
    {
        public override void Validate(System.Security.Cryptography.X509Certificates.X509Certificate2 certificate)
        {
            // Insert validation logic here.
        }
    }
}

How to Configure Windows Credential Mapping

The following code snippet shows how to configure Windows credential mapping:

X509SecurityTokenHandler x509Handler = new X509SecurityTokenHandler();
        x509Handler.MapToWindows = true;

        UserNameSecurityTokenHandler usernameHandler = new WindowsUserNameSecurityTokenHandler();

        Saml11SecurityTokenHandler saml11Handler = new Saml11SecurityTokenHandler();
        saml11Handler.SamlSecurityTokenRequirement.MapToWindows = true;

        Saml2SecurityTokenHandler saml2Handler = new Saml2SecurityTokenHandler();
        saml2Handler.SamlSecurityTokenRequirement.MapToWindows = true;