<add>

Article
03/30/2017

Adds the specified security token handler to the token handler collection.

<configuration>
  <system.identityModel>
    <identityConfiguration>
      <securityTokenHandlers>
        <add>

Syntax

<system.identityModel>  
  <identityConfiguration>  
    <securityTokenHandlers>  
      <add type=xs:string>  
        <optionalConfigurationElement>  
        </optionalConfigurationElement>  
      </add>  
    </securityTokenHandlers>  
  </identityConfiguration>  
</system.identityModel>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

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

Child Elements

Element	Description
<samlSecurityTokenRequirement>	Provides configuration for the SamlSecurityTokenHandler class, the Saml2SecurityTokenHandler class, or a derived class of either of these classes.
<sessionTokenRequirement>	Provides configuration for the SessionSecurityTokenHandler class or derived classes.
<userNameSecurityTokenHandlerRequirement>	Provides configuration for the MembershipUserNameSecurityTokenHandler class or derived classes.
<x509SecurityTokenHandlerRequirement>	Provides optional configuration for the X509SecurityTokenHandler class or derived classes.

Parent Elements

Element	Description
<securityTokenHandlers>	Specifies a collection of security token handlers that are registered with the endpoint.

Remarks

The <add> element can take a single child element that specifies the configuration for the token handler. This is dependent on whether the handler class referenced through the type attribute of the <add> element provides support for this feature. Token handler classes that provide this feature must expose a constructor that takes an XmlElement object.

public class CustomTokenHandler : Microsoft.IdentityModel.Tokens.SecurityTokenHandler  
{  
    public CustomTokenHandler( XmlElement customConfig )  
    {  
    }  
}

Several of the built-in security token handler classes do provide this functionality. These classes are SamlSecurityTokenHandler, Saml2SecurityTokenHandler, MembershipUserNameSecurityTokenHandler, X509SecurityTokenHandler, and SessionSecurityTokenHandler.

Important

The token handler collection can only contain a single handler of any given type. This means, for example, that if you want to add a handler that is derived from the Saml2SecurityTokenHandler class to the collection, you must first remove the Saml2SecurityTokenHandler, which is present by default, from the collection. You can use the <remove> element to remove a single handler from the collection or use the <clear> element to remove all handlers from the collection.

Settings specified on a handler override equivalent settings specified on the token handler collection under the <securityTokenHandlerConfiguration> element and those specified at the service-level under the <identityConfiguration> element.

Example

The following XML shows the use of the <add> and <remove> elements to replace the default session token handler with a custom session token handler. The XML is taken from the ClaimsAwareWebFarm sample.

<securityTokenHandlers>  
  <remove type="System.IdentityModel.Tokens.SessionSecurityTokenHandler, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />  
  <add type="System.IdentityModel.Services.Tokens.MachineKeySessionSecurityTokenHandler, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />  
</securityTokenHandlers>

Share via