Write a custom security token and handler in Windows Identity Foundation


In this article I will demonstrate how to write a token handler for a custom token in Windows Identity Foundation (WIF). The likely circumstances for requiring a new token type are:

  • The token type is pre-existing and needs to be federated
  • The new token type is an extension to a token type already supported by WIF

However, the purpose of this article is to demonstrate one of the extensibility points of WIF and so the reasons for creating a new token type are not so important.

Before continuing I should point out that I am not creating a new wire protocol for conveying tokens, but instead using an existing wire protocol (WS-Federation) to pass a new token type. WS-Federation is well suited to this because it is a means of conveying WS-Trust tokens using browser redirects. In turn, WS-Trust is essentially a container for …. well, any token type you like, and that is why we can create a new token type without risk of breaking any standards.

I am going to take a trial and error approach to this so that you can see some of the common pitfalls. I will simply fire a new token, wrapped within a WS-Trust 1.3 envelope and conveyed by the WS-Federation Passive Requestor Profile, as a sign-in response message to the Relying Party (RP) application. Then, I will fix the RP application by reacting to the errors that occur. Using this methodology you may get a fuller understanding of how to implement a new token handler and token.

First I need a Security Token Service (STS) to send a custom token to the RP. To do this I have captured a sign in response using Http Watch (a really good and easy to use HTTP sniffer), changed the token within the  WS-Federation wresult parameter, and hardcoded it as the STS response; this was achieved using a ASP.NET website with a HttpHandler implementation.

The custom token to be consumed by the RP looks like the following:

<m:MyCustomToken 
xmlns:m="urn:mycustomtoken"
m:Id="D416881A-130B-4AFF-8091-F412D7440E39"
m:Issuer="urn:mycustomtokenhandlersts"
m:Audience="https://mycustomtokenhandlerwebsite/"
m:ValidFrom="2011-01-01"
m:ValidTo="2099-12-31">
<m:Claim Name="GivenName" Namespace="urn:givenname">John</m:Claim>
<m:Claim Name="Surname" Namespace="urn:surname">Doe</m:Claim>
<m:Claim Name="Role" Namespace="urn:role">Manager</m:Claim>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
<Reference URI="">
<Transforms>
<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>gK8K+94DbXsVHxE8X3ulh45WcEM=</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>… removed for brevity …</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>… removed for brevity …</X509Certificate>
</X509Data>
</KeyInfo>
</Signature>
</m:MyCustomToken>

It contains many of the characteristics of common token types:

  • Id – a unique identifier for the token (can be used to detect replay attacks)
  • Namespace – the namespace for the token
  • Issuer – the entity that issued the token to the RP
  • ValidFrom/ValidTo – the validity period of the token
  • Audience – the entity that the token is intended for
  • Claims – a set of authoritative statements about the identity described by the token
  • Digital signature – ensures that the message cannot be tampered with and also enforces the authoritative nature of the message

The <microsoft.identityModel> configuration section of the RP config file currently has no awareness of the new token type:

<microsoft.identityModel>
<service>
<audienceUris>
<add value="https://mycustomtokenhandlerwebsite/" />
</audienceUris>
<federatedAuthentication>
<wsFederation
passiveRedirectEnabled="true"
issuer="http://localhost:29460/MyCustomTokenHandlerSTS/STSHandler.ashx"
realm="https://mcthw"
requireHttps="false" />
<cookieHandler requireSsl="false" />
</federatedAuthentication>
<issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry">
<trustedIssuers />
</issuerNameRegistry>
</service>
</microsoft.identityModel>

OK, by browsing to the RP home page the browser is automatically redirected to the STS and the custom token is returned to the RP … Error!

 
“ID4014: A SecurityTokenHandler is not registered to read security token (‘MyCustomToken’, ‘urn:mycustomtoken’)”

This seems reasonable as I have not yet made any effort to recognise the token. I therefore need the bare bones of a custom SecurityTokenHandler implementation:

using System;
using Microsoft.IdentityModel.Tokens;

/// <summary>
/// Summary description for MyCustomTokenHandler
/// </summary>
public class MyCustomTokenHandler : SecurityTokenHandler
{
public MyCustomTokenHandler()
{
}

public override string[] GetTokenTypeIdentifiers()
{
throw new NotImplementedException();
}

public override Type TokenType
{
get { throw new NotImplementedException(); }
}
}

I also need a custom System.IdentityModel.Tokens.SecurityToken implementation representing the token type to be handled:

 
using System;
using System.IdentityModel.Tokens;

/// <summary>
/// Summary description for MyCustomToken
/// </summary>
public class MyCustomToken : SecurityToken
{
public MyCustomToken()
{
}

public override string Id
{
get { throw new NotImplementedException(); }
}

public override ReadOnlyCollection<SecurityKey> SecurityKeys
{
get { throw new NotImplementedException(); }
}

public override DateTime ValidFrom
{
get { throw new NotImplementedException(); }
}

public override DateTime ValidTo
{
get { throw new NotImplementedException(); }
}
}

Finally, I need to reference the handler in the RP config file by adding in a <securityTokenHandlers> element:

 
<securityTokenHandlers>
<add type="MyCustomTokenHandler" />
</securityTokenHandlers>

Browse to the RP again … Error!

 
“The method or operation is not implemented”
 
This occurs because I need to implement the handlers GetTokenTypeIdentifiers method to return the namespace of the new token, and also the TokenType property to return the tokens type:
 
public override string[] GetTokenTypeIdentifiers()
{
return new string[] { "urn:mycustomtoken" };
}

public override Type TokenType
{
get { return typeof(MyCustomToken); }
}

Browse to the RP again … Error!

 
“ID4014: A SecurityTokenHandler is not registered to read security token (‘MyCustomToken’, ‘urn:mycustomtoken’)”
 
This is a bit strange as I have implemented all of the methods mandated by the base class. After a quick peek into the WIF source I found the following:
 
public virtual bool CanReadToken(XmlReader reader)
{
return false;
}
 
By default all security token handler implementations are excluded as possible candidates for parsing the token! I therefore need to override this method and perform some checks on the incoming token to make sure that my code genuinely can read the token:
 
public override bool CanReadToken(XmlReader reader)
{
if (reader.LocalName.Equals("MyCustomToken") &&
reader.NamespaceURI.Equals("urn:mycustomtoken"))
{
return true;
}

return false;
}

Browse to the RP again … Error!

 
“ID4008: ‘SecurityTokenHandler’ does not provide an implementation for ‘ReadToken’”
 
This seems self explanatory as I have indicated that I can read the token but have provided no code to do so. I need a SecurityToken implementation but the SecurityToken base class only offers a few read-only properties. It therefore seems that I must do most of the work myself. To achieve this I have created a internal representation of the token:
 
using System;
using System.Collections.Generic;
using Microsoft.IdentityModel.Claims;

/// <summary>
/// Summary description for MyCustomTokenInternal
/// </summary>
public class MyCustomTokenInternal
{
public string Id { get; set; }

public DateTime ValidFrom { get; set; }

public DateTime ValidTo { get; set; }

public string Audience { get; set; }

public string Issuer { get; set; }

public IEnumerable<Claim> Claims { get; set; }
}

I have then used the internal token type to populate an instance of MyCustomToken in the ReadToken implementation of MyCustomTokenHandler:
public override SecurityToken ReadToken(XmlReader reader)
{
// Check token signature using EnvelopedSignatureReader (more performant but more complex to use)
// or SignedXml (easier to use but less performant)

MyCustomToken token = new MyCustomToken(
new MyCustomTokenInternal()
{
Id = reader.GetAttribute("Id", TokenNamespace),
ValidFrom = XmlConvert.ToDateTime(reader.GetAttribute("ValidFrom", TokenNamespace)),
ValidTo = XmlConvert.ToDateTime(reader.GetAttribute("ValidTo", TokenNamespace)),
Audience = reader.GetAttribute("Audience", TokenNamespace),
Issuer = reader.GetAttribute("Issuer", TokenNamespace),
Claims = from el in XElement.Load(reader).Elements(XName.Get("Claim", TokenNamespace)) select new Claim(el.Attribute("Namespace").Value, el.Value)
});

return token;
}

Browse to the RP again … Error!

 
“ID4011: A SecurityTokenHandler is not registered to validate token type ‘MyCustomToken’”
 
Ok … as well as being able to read the token, the token handler also needs to be able to validate it. I therefore need to override the ValidateToken method and I am also going to pre-empt the possibility that I need to provide a ValidateToken implementation (as for CanReadToken/ReadToken):
 
public override bool CanValidateToken
{
get
{
return true;
}
}

public override ClaimsIdentityCollection ValidateToken(SecurityToken token)
{
ClaimsIdentityCollection idColl = new ClaimsIdentityCollection();
IClaimsIdentity id = new ClaimsIdentity((token as MyCustomToken).Claims);
idColl.Add(id);
return idColl;
}


Browse to the RP again … Success!
 
image_2_2F5D7C2C[1]
 
Finally, to prove that the token conditions are being honoured by WIF I have changed the ValidTo date to a time in the past. When I now attempt to browse to the RP I get the following error:
 
“Specified argument was out of the range of valid values. Parameter name: validFrom”
 
Which is slightly odd as it is the ValidTo date that is incorrect, but at least an error occurs.
 
In conclusion, I have shown how it is possible to consume a custom token type in WIF using the SecurityToken and SecurityTokenHandler classes.
 
Finally I have included the complete classes below for reference.
 
Have fun!
 
Written by Bradley Cotier
MyCustomTokenHandler:
using System;
using System.IdentityModel.Tokens;
using System.Linq;
using System.Xml;
using System.Xml.Linq;
using Microsoft.IdentityModel.Claims;
using Microsoft.IdentityModel.Tokens;

/// <summary>
/// Summary description for MyCustomTokenHandler
/// </summary>
public class MyCustomTokenHandler : SecurityTokenHandler
{
private const string TokenNamespace = "urn:mycustomtoken";

public MyCustomTokenHandler()
{
}

public override string[] GetTokenTypeIdentifiers()
{
return new string[] { TokenNamespace };
}

public override Type TokenType
{
get { return typeof(MyCustomToken); }
}

public override bool CanReadKeyIdentifierClause(XmlReader reader)
{
if (reader.LocalName.Equals("X509Data"))
{
return true;
}

return false;
}

public override bool CanReadToken(XmlReader reader)
{
if (reader.LocalName.Equals("MyCustomToken") &&
reader.NamespaceURI.Equals("urn:mycustomtoken"))
{
return true;
}

return false;
}

public override SecurityToken ReadToken(XmlReader reader)
{
// Check token signature using EnvelopedSignatureReader (more performant but more complex to use)
// or SignedXml (easier to use but less performant)

MyCustomToken token = new MyCustomToken(
new MyCustomTokenInternal()
{
Id = reader.GetAttribute("Id", TokenNamespace),
ValidFrom = XmlConvert.ToDateTime(reader.GetAttribute("ValidFrom", TokenNamespace)),
ValidTo = XmlConvert.ToDateTime(reader.GetAttribute("ValidTo", TokenNamespace)),
Audience = reader.GetAttribute("Audience", TokenNamespace),
Issuer = reader.GetAttribute("Issuer", TokenNamespace),
Claims = from el in XElement.Load(reader).Elements(XName.Get("Claim", TokenNamespace)) select new Claim(el.Attribute("Namespace").Value, el.Value)
});

return token;
}

public override bool CanValidateToken
{
get
{
return true;
}
}

public override ClaimsIdentityCollection ValidateToken(SecurityToken token)
{
ClaimsIdentityCollection idColl = new ClaimsIdentityCollection();

IClaimsIdentity id = new ClaimsIdentity((token as MyCustomToken).Claims);

idColl.Add(id);

return idColl;
}
}

MyCustomToken:
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.IdentityModel.Tokens;
using Microsoft.IdentityModel.Claims;

/// <summary>
/// Summary description for MyCustomToken
/// </summary>
public class MyCustomToken : SecurityToken
{
private MyCustomTokenInternal tokenInt;

public MyCustomToken(MyCustomTokenInternal tokenInt)
{
this.tokenInt = tokenInt;
}

public override string Id
{
get { return this.tokenInt.Id; }
}

public override ReadOnlyCollection<SecurityKey> SecurityKeys
{
get { return null; }
}

public override DateTime ValidFrom
{
get { return this.tokenInt.ValidFrom; }
}

public override DateTime ValidTo
{
get { return this.tokenInt.ValidTo; }
}

public IEnumerable<Claim> Claims
{
get { return this.tokenInt.Claims; }
}
}

MyCustomTokenInternal:
using System;
using System.Collections.Generic;
using Microsoft.IdentityModel.Claims;

/// <summary>
/// Summary description for MyCustomTokenInternal
/// </summary>
public class MyCustomTokenInternal
{
public string Id { get; set; }

public DateTime ValidFrom { get; set; }

public DateTime ValidTo { get; set; }

public string Audience { get; set; }

public string Issuer { get; set; }

public IEnumerable<Claim> Claims { get; set; }
}

RP web.config <microsoft.identityModel> config section:
<microsoft.identityModel>
<service>
<audienceUris>
<add value="https://mycustomtokenhandlerwebsite/" />
</audienceUris>
<federatedAuthentication>
<wsFederation
passiveRedirectEnabled="true"
issuer="http://localhost:29460/MyCustomTokenHandlerSTS/STSHandler.ashx"
realm="http://localhost:58724/MyCustomTokenHandlerWebsite/"
requireHttps="false" />
<cookieHandler requireSsl="false" />
</federatedAuthentication>
<issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry">
<trustedIssuers />
</issuerNameRegistry>
<securityTokenHandlers>
<add type="MyCustomTokenHandler" />
</securityTokenHandlers>
</service>
</microsoft.identityModel>

Comments (1)

  1. granadacoder says:

    Thanks..the "walk through" step by step was helpful.

    I am using System.Identity model (this is what you're on dotnet 4.5 or above)……

    Here is one thing I had to change.  The "firehose" nature of the XmlReader was giving me trouble.

    I used the XmlReader to create an XDocument, and persisted it so the next call it would be available.

       public class MyCustomTokenHandler : SecurityTokenHandler

       {

           public const string XmlNsSaml = "urn:something";

           public const string FirstElementLocalName = "Assertion";

           public MyCustomTokenHandler()

           { }

           private XDocument SourceData { get; set; }

           public override string[] GetTokenTypeIdentifiers()

           {

               return new string[] { XmlNsSaml };

           }

           public override Type TokenType

           {

               get { return typeof(MyCustomToken); }

           }

           public override bool CanReadToken(XmlReader reader)

           {

               /* We need to have access to all the data in the reader in both this method (CanReadToken) and ReadToken, so convert to XDocument and persist as member variable to have it around */

               this.SourceData = XDocument.Load(reader); ;

               ///reader.MoveToContent();

               //if (reader.LocalName.Equals("Assertion") &&

               //    reader.NamespaceURI.Equals(XmlNsSaml))

               if (null != this.SourceData)

               {

                   XElement xele = this.SourceData.Elements().FirstOrDefault();

                   if (null != xele)

                   {

                       if (null != xele.Name)

                       {

                           if (xele.Name.LocalName.Equals(FirstElementLocalName, StringComparison.OrdinalIgnoreCase) && xele.Name.NamespaceName.Equals(XmlNsSaml, StringComparison.OrdinalIgnoreCase))

                           {

                               return true;

                           }

                       }

                   }

               }

               return false;

           }

           public override SecurityToken ReadToken(XmlReader reader)

           {

               XDocument xDoc = this.SourceData;

    /* do stuff with the xDoc here to create the MyCustomTokenInternal and then the MyCustomToken */

    /* code not shown that does that */

    }