SecurityTokenHandler Class

Reference

Definition

Namespace:: System.IdentityModel.Tokens

Assembly:: System.IdentityModel.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

The abstract base class for security token handlers.

public ref class SecurityTokenHandler abstract : System::IdentityModel::Configuration::ICustomIdentityConfiguration

public abstract class SecurityTokenHandler : System.IdentityModel.Configuration.ICustomIdentityConfiguration

type SecurityTokenHandler = class
    interface ICustomIdentityConfiguration

Public MustInherit Class SecurityTokenHandler
Implements ICustomIdentityConfiguration

Inheritance: Object
SecurityTokenHandler

Derived: System.IdentityModel.Tokens.EncryptedSecurityTokenHandler

System.IdentityModel.Tokens.KerberosSecurityTokenHandler

System.IdentityModel.Tokens.RsaSecurityTokenHandler

System.IdentityModel.Tokens.Saml2SecurityTokenHandler

System.IdentityModel.Tokens.SamlSecurityTokenHandler

More…

Implements: ICustomIdentityConfiguration

Examples

The code examples in all of the SecurityTokenHandler topics are taken from the Custom Token sample. This sample provides custom classes that enable processing of Simple Web Tokens (SWT). For information about this sample and other samples available for WIF and where to download them, see WIF Code Sample Index. The following XML shows how to add the SWT token handler to the token handlers collection.

<system.identityModel>
  <identityConfiguration saveBootstrapContext="true">
    <issuerTokenResolver type="SimpleWebToken.CustomIssuerTokenResolver, SimpleWebToken">
      <AddAudienceKeyPair  symmetricKey="wAVkldQiFypTQ+kdNdGWCYCHRcee8XmXxOvgmak8vSY=" audience="http://localhost:19851/" />
    </issuerTokenResolver>
    <issuerNameRegistry type="RelyingParty.TrustedIssuerNameRegistry, RelyingParty"/>
    <audienceUris>
      <add value="http://localhost:19851/"/>
    </audienceUris>
    <securityTokenHandlers>
      <add type="SimpleWebToken.SimpleWebTokenHandler, SimpleWebToken" />
    </securityTokenHandlers>
  </identityConfiguration>
</system.identityModel>

Remarks

The SecurityTokenHandler class is the base class from which all security token handlers derive. A security token handler is responsible for:

Validating security tokens (SecurityToken) of the type it is designed to process and packaging the claims contained in the token into a ClaimsIdentity object.
Serializing and deserializing security tokens of the type it is designed to process.
Serializing and deserializing key identifier clauses (SecurityKeyIdentifierClause) that refer to tokens of the type it is designed to process to and from <wsse:SecurityTokenReference> elements.
Creating security tokens from a SecurityTokenDescriptor object passed by implementations of the SecurityTokenService class.
Creating key identifier clauses from a security token for implementations of the SecurityTokenService class.

Windows Identity Foundation (WIF) ships the following security token handlers out of the box:

Most of these classes expose additional members that implement functionality that is specific to the processing of the tokens for which the class is designed. In many cases it may be better to derive from one of these classes rather than directly from the SecurityTokenHandler class.

A security token handler can be added or removed from a token handler collection by specifying the <add>, <remove>, or <clear> elements under the <securityTokenHandlers> element in a configuration file. The SecurityTokenHandlerConfiguration object that contains the configuration settings for the handler collection can be accessed through the Configuration property and the handler collection that the token handler is a member of can be accessed from the ContainingCollection property. You can override the LoadCustomConfiguration method to process any custom configuration elements that your handler takes.

The SecurityTokenHandler class exposes several other properties and methods. Depending on the functionality that you choose to implement, you may override some or all of these members.

You must override the TokenType property and the GetTokenTypeIdentifiers method to provide the WIF infrastructure with information about the type of security token that your class is designed to process.

Validation, serialization, and deserialization functionality is exposed through properties or methods that indicate whether the handler can perform a specific function combined with the method or methods that implement the functionality. The following list pairs the properties or methods that indicate functionality with the methods that implement that functionality:

The CanValidateToken property and the ValidateToken method: Validates a token and packages the claims contained in the token into a ClaimsIdentity.
The CanWriteToken property and the WriteToken methods: Token serialization.
The CanReadToken methods and the ReadToken methods: Token deserialization.
The CanReadKeyIdentifierClause method and the ReadKeyIdentifierClause method: Deserializing key identifier clauses.
The CanWriteKeyIdentifierClause method and the WriteKeyIdentifierClause method: Serializing key identifier clauses.

The CreateToken and the CreateSecurityTokenReference methods are called from the pipeline in implementations of the SecurityTokenService class.

The DetectReplayedToken method is called by the WIF infrastructure to determine whether the specified token has already been received. By default this method returns false, which indicates that the token has not already been received. You can override the method and provide logic to detect replayed tokens.

Constructors

SecurityTokenHandler()

Called from constructors in derived classes to initialize the SecurityTokenHandler class.

Properties

CanValidateToken	Gets a value that indicates whether the handler supports validation of security tokens.
CanWriteToken	Gets a value that indicates whether the handler can serialize security tokens.
Configuration	Gets or sets the SecurityTokenHandlerConfiguration object that provides configuration for the current instance.
ContainingCollection	Gets the token handler collection that contains the current instance.
TokenType	When overridden in a derived class, gets the type of the security token that is processed by this instance.

Methods

CanReadKeyIdentifierClause(XmlReader)	Returns a value that indicates whether the XML element referred to by the specified XML reader is a key identifier clause that can be deserialized by this instance.
CanReadToken(String)	Returns a value that indicates whether the specified string can be deserialized as a token of the type processed by this instance.
CanReadToken(XmlReader)	Returns a value that indicates whether the XML element referenced by the specified XML reader can be read as a token of the type processed by this instance.
CanWriteKeyIdentifierClause(SecurityKeyIdentifierClause)	Returns a value that indicates whether the specified key identifier clause can be serialized by this instance.
CreateSecurityTokenReference(SecurityToken, Boolean)	When overridden in a derived class, creates the security token reference for tokens processed by that class. This method is typically called by a security token service (STS).
CreateToken(SecurityTokenDescriptor)	When overridden in a derived class, creates a security token using the specified token descriptor. This method is called by a security token service (STS).
DetectReplayedToken(SecurityToken)	When overridden in a derived class, throws an exception if the specified token is detected as being replayed.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetTokenTypeIdentifiers()	When overridden in a derived class, returns the set of URIs that are used in requests to identify a token of the type processed by the derived class.
GetType()	Gets the Type of the current instance. (Inherited from Object)
LoadCustomConfiguration(XmlNodeList)	When overridden in a derived class, loads custom configuration from XML.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ReadKeyIdentifierClause(XmlReader)	When overridden in a derived class, deserializes the XML referenced by the specified XML reader to a key identifier clause that references a token processed by the derived class.
ReadToken(String)	When overridden in a derived class, deserializes the specified string to a token of the type processed by the derived class.
ReadToken(XmlReader, SecurityTokenResolver)	When overridden in a derived class, deserializes the XML referenced by the specified XML reader to a token of the type processed by the derived class by using the specified token resolver.
ReadToken(XmlReader)	When overridden in a derived class, deserializes the XML referenced by the specified XML reader to a token of the type processed by the derived class.
ToString()	Returns a string that represents the current object. (Inherited from Object)
TraceTokenValidationFailure(SecurityToken, String)	Traces the failure event during the validation of security tokens when tracing is enabled.
TraceTokenValidationSuccess(SecurityToken)	Traces the successful validation of security tokens event when tracing is enabled.
ValidateToken(SecurityToken)	When overridden in a derived class, validates the specified security token. The token must be of the type processed by the derived class.
WriteKeyIdentifierClause(XmlWriter, SecurityKeyIdentifierClause)	When overridden in a derived class, serializes the specified key identifier clause to XML. The key identifier clause must be of the type supported by the derived class.
WriteToken(SecurityToken)	When overridden in a derived class, serializes the specified security token to a string. The token must be of the type processed by the derived class.
WriteToken(XmlWriter, SecurityToken)	When overridden in a derived class, serializes the specified security token to XML. The token must be of the type processed by the derived class.

Applies to

Share via