Custom Token Handlers
This topic discusses token handlers in WIF and how they are used to process tokens. The topic also covers what is necessary to create custom token handlers for token types that are not supported by default in WIF.
Introduction to Token Handlers in WIF
WIF relies on security token handlers to create, read, write, and validate tokens for a relying party (RP) application or a security token service (STS). Token handlers are extensibility points for you to add a custom token handler in the WIF pipeline, or to customize the way that an existing token handler manages tokens. WIF provides nine built-in security token handlers that can be modified or entirely overridden to change the functionality as necessary.
Built-In Security Token Handlers in WIF
WIF 4.5 includes nine security token handler classes that derive from the abstract base class SecurityTokenHandler:
Adding a Custom Token Handler
Some token types, such as Simple Web Tokens (SWT) and JSON Web Tokens (JWT) do not have built-in token handlers provided by WIF. For these token types and for others that do not have a built-in handler, you need to perform the following steps to create a custom token handler.
Adding a custom token handler
Create a new class that derives from SecurityTokenHandler.
Override the following methods and provide your own implementation:
Add a reference to the new custom token handler in the Web.config or App.config file, within the <system.identityModel> section that applies to WIF. For example, the following configuration markup specifies a new token handler named MyCustomTokenHandler that resides in the CustomToken namespace.
<system.identityModel> <identityConfiguration saveBootstrapContext="true"> <securityTokenHandlers> <add type="CustomToken.MyCustomTokenHandler, CustomToken" /> </securityTokenHandlers> </identityConfiguration> </system.identityModel>
Note that if you are providing your own token handler to handle a token type that already has a built-in token handler, you need to add a <remove> element to drop the default handler and use your custom handler instead. For example, the following configuration replaces the default SamlSecurityTokenHandler with the custom token handler:
<system.identityModel> <identityConfiguration saveBootstrapContext="true"> <securityTokenHandlers> <remove type="System.IdentityModel.Tokens.SamlSecurityTokenHandler, System.IdentityModel, Version=188.8.131.52, Culture=neutral, PublicKeyToken=abcdefg123456789"> <add type="CustomToken.MyCustomTokenHandler, CustomToken" /> </securityTokenHandlers> </identityConfiguration> </system.identityModel>