Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Security Token Handler Configuration

Windows Identity Foundation
[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.

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="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
            <roleClaimType value="schemas.microsoft.com/ws/2006/04/identity/claims/role" />
        </samlSecurityTokenRequirement>
    </add>

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="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
        </samlSecurityTokenRequirement>
    </add>

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>

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>

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>

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



Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.