Security Token Handler Collection Configuration

  • Article

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

You can specify one or more named collections of security token handlers in a service configuration by using the <securityTokenHandlers> element.

securityTokenHandlers Element

Specifies a collection of security token handlers that are registered with the endpoint. A collection of handlers is represented by the SecurityTokenHandlerCollection class. You can specify a name for the collection by using the name attribute. The only names that the framework handles are "ActAs" and "OnBehalfOf". If handlers exist in these collections, they are used by a security token service (STS) instead of the default handlers when processing ActAs and OnBehalfOf tokens.

By default, the collection is populated with the following handler types: Saml11SecurityTokenHandler, Saml2SecurityTokenHandler, KerberosSecurityTokenHandler, WindowsUserNameSecurityTokenHandler, RsaSecurityTokenHandler, X509SecurityTokenHandler, and EncryptedSecurityTokenHandler. You can modify the collection by using the <add>, <remove>, and <clear/> elements. You must ensure that only a single handler of any particular type exists in the collection. For example, if you derive a handler from the Saml2SecurityTokenHandler class, either your handler or the Saml2SecurityTokenHandler may be configured in a single collection, but not both.

Use the <securityTokenHandlerConfiguration> element to specify configuration settings for the handlers in the collection. Settings specified through this element override those specified on the service. Some handlers (including several of the built-in handler types) can support additional configuration through a child element of the <add> element. For more information, see Security Token Handler Configuration. Settings specified on a handler override equivalent settings specified on the collection or the service.

Syntax:

<microsoft.identityModel>
    <service>
        <securityTokenHandlers> 
            <securityTokenHandlerConfiguration> ... </securityTokenHandlerConfiguration>
            <add type=String>
                <customConfigurationElement> ... </customConfigurationElement>
            </add>
            <clear/>
            <remove type=String/> 
        </securityTokenHandlers>
    </service>
</microsoft.identityModel>

Parent Element: <service>

Child Elements:

  • <securityTokenHandlerConfiguration>

  • <add>

  • <clear>

  • <remove>

Attributes:

Attribute Name Type Description

name

String

Specifies the name of a token handler collection. Named collections are used by the framework for processing tokens only in the following circumstances. The only values recognized by the framework are “ActAs” and “OnBehalfOf”. If token handler collections are specified with either of these names, the collection will be used when processing ActAs or OnBehalfOf tokens respectively.

Example:

securityTokenHandlerConfiguration Element

Provides configuration for the collection of token handlers. This section provides property values for a SecurityTokenHandlerConfiguration object. Settings configured in this section override those configured on the service. Some of these settings can, in turn, be overridden by settings that are specified when a handler is added to the security token handler collection. For more information, see Security Token Handler Configuration.

Parent Element: <securityTokenHandlers>

Child Elements:

  • <audienceUris>

  • <certificateValidation>

  • <issuerNameRegistry>

  • <issuerTokenResolver>

  • <maximumClockSkew>

  • <serviceTokenResolver>

Attributes: none

Example:

<microsoft.identityModel>
  <service>
    <securityTokenHandlers> 
      <securityTokenHandlerConfiguration>

        <audienceUris>
          <clear/>
          <add value="http://www.example.com/myapp/" />
          <remove value="http://www.example.com/myapp/" />
        </audienceUris>

        <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel">
          <trustedIssuers>
            <add thumbprint="97249e1a5fa6bee5e515b82111ef524a4c9158de" name="contoso.com" />
            <remove thumbprint="97249e1a5fa6bee5e515b82111ef524a4c9158de" />
            <clear/>
          </trustedIssuers>
        </issuerNameRegistry>

        <issuerTokenResolver type="MyNamespace.CustomTokenResolver, MyAssembly" />

        <serviceTokenResolver type="MyNamespace.CustomTokenResolver, MyAssembly" />

      </securityTokenHandlerConfiguration>
    </securityTokenHandlers>
  </Service>
</microsoft.identityModel>

audienceUris Element

Specifies the set of URIs that are acceptable identifiers of this relying party. Tokens will not be accepted unless they are scoped for one of the allowed audience URIs. By default, the collection is empty; use <add>, <clear>, and <remove> elements to modify the collection. An <audienceUris> element can be specified at the service level under the <service> element or on the security token handler collection level under the <securityTokenHandlerConfiguration> element. Settings on a token handler collection override those specified on the service. Saml11SecurityTokenHandler and Saml2SecurityTokenHandler objects use the values in the audience URI collection to configure any allowed audience URI restrictions in SamlSecurityTokenRequirement objects.

Syntax:

<microsoft.identityModel>
    <service>
        <!-- The <audiencUris> element may also be specified on the service configuration -->
        <securityTokenHandlers>
            <securityTokenHandlerConfiguration>
                <audienceUris mode="Always/Never/BearerKeyOnly">
                    <add value=URI/>
                    <clear/>
                    <remove value=URI/> 
                </audienceUris> 
            </securityTokenHandlerConfiguration>
        </securityTokenHandlers>
    </service>
</microsoft.identityModel>

Parent Element: <service>, <securityTokenHandlerConfiguration>

Child Elements:

  • <add>

  • <clear>

  • <remove>

Attributes:

Attribute Name Description

mode

An AudienceUriMode value that specifies whether the audience restriction should be applied to an incoming token. The possible values are “Always”, “Never”, and “BearerKeyOnly”. The default is “Always”.

Example:

    <audienceUris>
        <!-- 
            <clear/> may be used to remove any URIs that may be in
            this configuration collection.
        -->
        <clear/>
            
        <!--
            Each <add> references an allowed audience URI.
        -->
        <add value="http://www.example.com/myapp/" />
           
        <!--
            Each <remove> removes an audience URI.
        -->
        <remove value="http://www.example.com/myapp/" />
            
    </audienceUris>

certificateValidation Element

Controls the settings that token handlers use to validate certificates. These settings are overridden if a specific handler is configured with its own validator. This element can also be specified in the service configuration.

Syntax:

<microsoft.identityModel>
    <service>
        <!-- The <certificateValidation> element may also be specified on the service configuration -->
        <securityTokenHandlers> 
            <securityTokenHandlerConfiguration>
                 <certificateValidation certificateValidationMode="None||ChainTrust||PeerTrust||PeerOrChainTrust||Custom"
                                       revocationMode="NoCheck||Offline||Online"
                                       trustedStoreLocation="CurrentLocation||LocalMachine" >
                     </certificateValidator type=String"
                 </certificateValidation>
            </securityTokenHandlerConfiguration>
        </securityTokenHandlers>
    </service>
</microsoft.identityModel>

Parent Element: <service>, <securityTokenHandlerConfiguration>

Child Elements:

  • <certificateValidator>

Attributes:

Attribute Name Description

certificateValidationMode

An X509CertificateValidationMode value that specifies the validation mode to use for the X.509 certificate. The default value is “PeerOrChainTrust”. To specify a custom validator, set this attribute to “Custom” and specify the validator using the <certificateValidator> element.

revocationMode

An X509RevocationMode value that specifies the revocation mode to use for the X.509 certificate. The default value is “Online”.

trustedStoreLocation

A StoreLocation value that specifies the X.509 certificate store. The default value is “LocalMachine”.

Example:

      <certificateValidation certificateValidationMode="PeerOrChainTrust"
                             revocationMode="Online"
                             trustedStoreLocation="LocalMachine" />

certificateValidator Element

This element specifies a custom type for certificate validation. This type is used only if the certificateValidationMode attribute of the <certificateValidation> element is set to "Custom".

Syntax:

<microsoft.identityModel>
    <service>
        <!-- The <certificateValidation> element may also be specified on the service configuration -->
        <securityTokenHandlers> 
            <securityTokenHandlerConfiguration>
                 <certificateValidation certificateValidationMode="None||ChainTrust||PeerTrust||PeerOrChainTrust||Custom"
                                       revocationMode="NoCheck||Offline||Online"
                                       trustedStoreLocation="CurrentLocation||LocalMachine" >
                     </certificateValidator type=String"
                 </certificateValidation>
            </securityTokenHandlerConfiguration>
        </securityTokenHandlers>
    </service>
</microsoft.identityModel>

Parent Element: <certificateValidation>

Child Elements: none

Attributes:

Attribute Name Description

type

A custom type that derives from the X509CertificateValidator class. Set the certificateValidationMode attribute of the <certificateValidation> element to "Custom" to use this type. For more information about how to specify the type attribute, see Custom Type References.

Example:

      <certificateValidation certificateValidationMode="Custom"
                             revocationMode="Online"
                             trustedStoreLocation="LocalMachine">
          <certificateValidator type="MyNamespace.CustomValidator, MyAssembly" />  
      </certificateValidation>

issuerNameRegistry Element

Configures an issuer name registry. All issuer tokens are validated using an issuer name registry. This is an object that derives from the IssuerNameRegistry class. The issuer name registry maps the issuer token to a string name. A custom issuer name registry type can be specified using the type attribute. The <issuerNameRegistry> element can have a single child element that provides custom configuration for the specified type.

WIF provides a single issuer name registry type out of the box, the ConfigurationBasedIssuerNameRegistry class. This class uses a set of trusted issuer certificates that are specified in configuration. It requires a child configuration element, <trustedIssuers>, under which the collection of trusted issuer certificates is configured. Trusted certificates are specified using the ASN.1 encoded form of the certificate thumbprint and are added the collection by using <add>, <clear>, or <remove> elements. The Example section shows how to specify a configuration-based issuer name registry.

Syntax:

<microsoft.identityModel>
    <service>
        <!-- The <issuerNameRegistry> element may also be specified on the service configuration -->
        <securityTokenHandlers> 
            <securityTokenHandlerConfiguration>
                <issuerNameRegistry type=String>
                    <customConfigurationElement>
                        ...       
                    </customeConfigurationElement>
                </issuerNameRegistry>
            </securityTokenHandlerConfiguration>
        </securityTokenHandlers>
    </Service>
</microsoft.identityModel>

Parent Element: <service>, <securityTokenHandlerConfiguration>

Child Elements:

  • A single child element may be specified. When the type attribute specifies the configuration-based issuer name registry (the ConfigurationBasedIssuerNameRegistry class), the <trustedIssuers> element must be specified. The <trustedIssuers> element can take <add>, <clear>, or <remove> elements as child elements.

Attributes:

Attribute Name Description

type

A type that derives from the IssuerNameRegistry class. For more information about how to specify a custom type, see Custom Type References.

Example:

    <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel">
        <trustedIssuers>
            <add thumbprint="97249e1a5fa6bee5e515b82111ef524a4c9158de" name="contoso.com" />
            <remove thumbprint="97249e1a5fa6bee5e515b82111ef524a4c9158de" />
            <clear/>
        </trustedIssuers>
    </issuerNameRegistry>

issuerTokenResolver Element

Registers an issuer token resolver. The issuer token resolver can be used to resolve the signing token on incoming tokens and messages. You must specify the type attribute. The type specified can be either IssuerTokenResolver or a custom type that derives from the IssuerTokenResolver class.

Syntax:

<microsoft.identityModel>
    <service>
        <!-- The <issuerTokenResolver> element may also be specified in the service configuration -->
        <securityTokenHandlers> 
            <securityTokenHandlerConfiguration>
                <issuerTokenResolver type=String />
            </securityTokenHandlerConfiguration>
        </securityTokenHandlers>
    </Service>
</microsoft.identityModel>

Parent Element: <service>, <securityTokenHandlerConfiguration>

Child Elements: none

Attributes:

Attribute Name Description

type

Either the IssuerTokenResolver type or a type that derives from the IssuerTokenResolver class. For more information about how to specify the type attribute, see Custom Type References.

Example:

    <issuerTokenResolver type="MyNamespace.CustomTokenResolver, MyAssembly" />

maximumClockSkew Element

Controls the maximum allowed clock skew when performing time-sensitive operations, such as validating the expiration time of a sign-in session.

Syntax:

<microsoft.identityModel>
    <service>
        <!-- The <maximumClockSkew> element may also be specified in the service configuration -->
        <securityTokenHandlers> 
            <securityTokenHandlerConfiguration>
                <maximumClockSkew value=TimeSpan />
            </securityTokenHandlerConfiguration>
        </securityTokenHandlers>
    </Service>
</microsoft.identityModel>

Parent Element: <service>, <securityTokenHandlerConfiguraiton>

Child Elements: none

Attributes:

Attribute Name Description

value

A TimeSpan that specifies the maximum allowed clock skew. The default is 5 minutes, “00:05:00”. For more information about how to specify TimeSpan values, see Timespan Values.

Example:

      <maximumClockSkew value="00:05:00" />

serviceTokenResolver Element

Registers a service token resolver. The service token resolver can be used to resolve the encryption token on incoming tokens and messages. You must specify the type attribute. The type specified can be either SecurityTokenResolver or a custom type that derives from the SecurityTokenResolver class.

Syntax:

<microsoft.identityModel>
    <service>
        <!-- The <serviceTokenResolver> element may also be specified in the service configuration -->
        <securityTokenHandlers> 
            <securityTokenHandlerConfiguration>
                <serviceTokenResolver type=String />
            </securityTokenHandlerConfiguration>
        </securityTokenHandlers>
    </Service>
</microsoft.identityModel>

Parent Element: <service>, <securityTokenHandlerConfiguration>

Child Elements: none

Attributes:

Attribute Name Description

type

Either the SecurityTokenResolver type or a type that derives from the SecurityTokenResolver class. For more information about how to specify the type attribute, see Custom Type References.

Example:

    <serviceTokenResolver type="MyNamespace.CustomTokenResolver, MyAssembly" />

add Element

Adds the specified token handler to the collection. The <add> element can contain a single child element that provides a custom configuration section. For more information about the built-in handlers that expose a configuration element, as well as creating token handlers that can expose a configuration element, see Security Token Handler Configuration.

Parent Element: <securityTokenHandlers>

Child Elements: Can take a single child element that provides custom configuration.

Attributes:

Attribute Name Description

type

The CLR type name of the token handler to be added. For more information about how to specify the type attribute, see Custom Type References.

Example:

        <add type="MyNamespace.CustomTokenHandler, MyAssembly">
          <customConfig myAttr="val">
            <customSubConfig>
            </customSubConfig>
          </customConfig>
        </add>

clear Element

Clears all token handlers from the current collection.

Parent Element: <securityTokenHandlers>

Child Elements: none

Attributes: none

Example:

        <clear />

remove Element

Removes the specified token handler from the collection.

Parent Element: <securityTokenHandlers>

Child Elements: none

Attributes:

Attribute Name Description

type

The CLR type name of the token handler to be removed. For more information about how to specify the type attribute, see Custom Type References.

Example:

        <remove type="Microsoft.IdentityModel.Tokens.Saml11.Saml11SecurityTokenHandler, Microsoft.IdentityModel" />

See Also

Reference

SecurityTokenHandlerCollection
SecurityTokenHandlerConfiguration

Concepts

Token Handlers