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

When used as a child element of the <securityTokenHandlers> element, 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 feature. These classes are Saml11SecurityTokenHandler, Saml2SecurityTokenHandler, MembershipUserNameSecurityTokenHandler, X509SecurityTokenHandler, and SessionSecurityTokenHandler. This topic describes the elements that configure these handlers.

Settings specified on a handler override equivalent settings specified on the security token handler collection and on the service.

samlSecurityTokenRequirement Element

Provides configuration for the Saml11SecurityTokenHandler class, the Saml2SecurityTokenHandler class, or a derived class of either of these classes. Represented by the SamlSecurityTokenRequirement class.

Syntax:

<microsoft.identityModel>
    <service>
        <securityTokenHandlers> 
            <add type="Microsoft.IdentityModel.Tokens.Saml11.Saml11SecurityTokenHandler, Microsoft.IdentityModel">
                  <samlSecurityTokenRequirement 
                                        issuerCertificateValidationMode="None||ChainTrust||PeerTrust||PeerOrChainTrust||Custom"
                                        issuerCertificateRevocationMode="NoCheck||Offline||Online"
                                        issuerCertificateTrustedStoreLocation="CurrentLocation||LocalMachine" 
                                        issuerCertificateValidator="Namespace.Class Assembly" 
                                        mapToWindows=Boolean
                                        useWindowsTokenService=Boolean>
                       <nameClaimType value=URI />
                       <roleClaimType value=URI />
                   </samlSecurityTokenRequirement>
             </add>
        </securityTokenHandlers>
    </service>
</microsoft.identityModel>

Parent Element: <add>

Child Elements:

• <nameClaimType>

• <roleClaimType>

Attributes:

Attribute Name	Type	Description
issuerCertificateValidationMode	X509CertificateValidationMode	An X509CertificateValidationMode value that specifies the validation mode to use for the X.509 certificate. The default value is “PeerOrChainTrust”.
issuerCertificateRevocationMode	X509RevocationMode	An X509RevocationMode value that specifies the revocation mode to use for the X.509 certificate. The default value is “Online”.
issuerCertificateTrustedStoreLocation	StoreLocation	A StoreLocation value that specifies the X.509 certificate store. The default value is “LocalMachine”.
issuerCertificateValidator		A custom type that derives from X509CertificateValidator. If the certificateValidationMode attribute is "Custom", an instance of this type is used for issuer certificate validation.
mapToWindows	Boolean	Specifies whether the token handler should map the validating token to a Windows account by using the incoming UPN claim. The default is “false”.
useWindowsTokenService	Boolean	Specifies whether the token handler should utilize the Windows Token Service to perform the log on operation for the mapToWindows feature. The default is “false”.

Example:

    <add type="Microsoft.IdentityModel.Tokens.Saml11.Saml11SecurityTokenHandler, Microsoft.IdentityModel">
        <samlSecurityTokenRequirement issuerCertificateValidationMode="PeerOrChainTrust"
                                      issuerCertificateRevocationMode="Online"
                                      issuerCertificateTrustedStoreLocation="LocalMachine"
                                      mapToWindows="false"
                                      useWindowsTokenService="false">

            <nameClaimType value="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
            <roleClaimType value="schemas.microsoft.com/ws/2006/04/identity/claims/role" />
        </samlSecurityTokenRequirement>
    </add>

nameClaimType Element

Sets the claim type that specifies the Name property. This value is used to search for a Claim in the ClaimsIdentityCollection returned by the ValidateToken method of this token handler, and the value of the claim is set as the name of the IIdentity generated from this token handler.

Parent Element: <samlSecurityTokenRequirement>

Child Elements: none

Attributes:

Attribute Name	Description
value	A string that specifies the URI that represents the claim type of the claim to use for the Name property.

Example:

    <add type="Microsoft.IdentityModel.Tokens.Saml11.Saml11SecurityTokenHandler, Microsoft.IdentityModel">
        <samlSecurityTokenRequirement>
            <nameClaimType value="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
        </samlSecurityTokenRequirement>
    </add>

roleClaimType Element

Specifies the set of claim type that defines the role type claims in the ClaimsIdentityCollection returned by the ValidateToken method of the token handler.

Parent Element: <samlSecurityTokenRequirement>

Child Elements: none

Attributes:

Attribute Name	Description
value	A string that specifies the URI that represents the claim type of the claim to use for the role claim type.

Example:

    <add type="Microsoft.IdentityModel.Tokens.Saml11.Saml11SecurityTokenHandler, Microsoft.IdentityModel">
        <samlSecurityTokenRequirement>
            <roleClaimType value="schemas.microsoft.com/ws/2006/04/identity/claims/role" />
        </samlSecurityTokenRequirement>
    </add>

usernameSecurityTokenHandlerRequirement Element

Provides configuration for the MembershipUserNameSecurityTokenHandler class or derived classes.

Syntax:

<microsoft.identityModel>
    <service>
        <securityTokenHandlers> 
            <add type="Microsoft.IdentityModel.Tokens.MembershipUserNameSecurityTokenHandler, Microsoft.IdentityModel">
                <userNameSecurityTokenHandlerRequirement membershipProviderName=String/>
            </add>
        </securityTokenHandlers>
    </service>
</microsoft.identityModel>

Parent Element: <add>

Child Elements: none

Attributes:

Attribute Name	Description
membershipProviderName	Specifies the MembershipProvider that should be used by the security token handler.

Example:

    <add type="Microsoft.IdentityModel.Tokens.MembershipUserNameSecurityTokenHandler, Microsoft.IdentityModel">
        <userNameSecurityTokenHandlerRequirement membershipProviderName="AspNetSqlProvider/>
    </add>

x509SecurityTokenHandlerRequirement Element

Provides optional configuration for the X509SecurityTokenHandler class or derived classes.

Syntax:

<microsoft.identityModel>
    <service>
        <securityTokenHandlers> 
            <add type="Microsoft.IdentityModel.Tokens.X509SecurityTokenHandler, Microsoft.IdentityModel">
                <x509SecurityTokenHandlerRequirement mapToWindows=Boolean 
                                               certificateValidationMode="None||ChainTrust||PeerTrust||PeerOrChainTrust||Custom"
                                               certificateValidator="Namespace.Class, Assembly" 
                                               revocationMode="NoCheck||Offline||Online" 
                                               trustedStoreLocation="CurrentUser||LocalMachine"
                                               useWindowsTokenService=Boolean/>
            </add>
        </securityTokenHandlers>
    </service>
</microsoft.identityModel>

Parent Element: <add>

Child Elements: none

Attributes:

Attribute Name	Type	Description
certificateValidationMode	X509CertificateValidationMode	An X509CertificateValidationMode value that specifies the validation mode to use for the X.509 certificate. The default value is “PeerOrChainTrust”.
certificateRevocationMode	X509RevocationMode	An X509RevocationMode value that specifies the revocation mode to use for the X.509 certificate. The default value is “Online”.
certificateTrustedStoreLocation	StoreLocation	A StoreLocation value that specifies the X.509 certificate store. The default value is “LocalMachine”.
certificateValidator		A custom type that derives from X509CertificateValidator. If the certificateValidationMode attribute is "Custom", an instance of this type is used for issuer certificate validation.
mapToWindows	Boolean	Specifies whether the token handler should map the validating token to a Windows account by using the incoming UPN claim. The default is “false”.
useWindowsTokenService	Boolean	Specifies whether the token handler should utilize the Windows Token Service to perform the log on operation for the mapToWindows feature. The default is “false”.

Example:

    <add type="Microsoft.IdentityModel.Tokens.X509SecurityTokenHandler, Microsoft.IdentityModel">
        <x509SecurityTokenHandlerRequirement mapToWindows="true" 
                                             certificateValidationMode="PeerOrChainTrust" 
                                             revocationMode="Online" 
                                             trustedStoreLocation="LocalMachine"
                                             useWindowsTokenService="true"/>
    </add>

sessionTokenRequirement Element

Provides configuration for the SessionSecurityTokenHandler class or derived classes.

Syntax:

<microsoft.identityModel>
    <service>
        <securityTokenHandlers> 
            <add type="Microsoft.IdentityModel.Tokens.SessionSecurityTokenHandler, Microsoft.IdentityModel">         
                <sessionTokenRequirement lifetime=TimeSpan
                                         saveBootstrapTokens=Boolean
                                         securityTokenCacheSize=Integer
                                         securityTokenCacheType="Microsoft.IdentityModel.MruSecurityTokenCache, Microsoft.IdentityModel"
                                         useWindowsTokenService=Boolean />
            </add>
        </securityTokenHandlers>
    </service>
</microsoft.identityModel>

Parent Element: <add>

Child Elements: none

Attributes:

Attribute Name	Type	Description
lifetime	Timespan	Specifies the lifetime of session tokens.
saveBootstrapTokens	Boolean	Specifies whether bootstrap tokens should be included in the session token.
securityTokenCacheSize	Integer	Specifies maximum number of entries in the security token cache.
securityTokenCacheType	String	References a custom type that must be derived from the SecurityTokenCache class.
useWindowsTokenService	Boolean	A value that specifies whether WindowsLogon tokens should be mapped to Windows accounts.

Example:

    <add type="Microsoft.IdentityModel.Tokens.SessionSecurityTokenHandler, Microsoft.IdentityModel">         
        <sessionTokenRequirement securityTokenCacheType="Microsoft.IdentityModel.MruSecurityTokenCache, Microsoft.IdentityModel"
                                 saveBootstrapTokens="true"
                                 securityTokenCacheSize="500"
                                 useWindowsTokenService="false"
                                 lifetime="10:00" />
    </add>

See Also

Reference

SamlSecurityTokenRequirement

Concepts

How to: Add a Custom Token Handler