WIF

Windows Identity Foundation

WIF in depth: Validating Security Tokens outside of WIF

Sometimes it is necessary to validate SecurityTokens issued by an Windows Identity Foundation (WIF) driven Identity Provider (IdP) in a Service Provider (SP) application that has no reference to WIF.

When it came to validating the xml signature of the token I ran into an exception on calling the CheckSignature() method of the SignedXml class:

System.Security.Cryptography.CryptographicException: 
SignatureDescription could not be created for the signature algorithm supplied.

What this exception message basically states is that it does not know the specified signature algorithm. The name of this algorithm is set by the corresponding xml attribute in the raw token data as http://www.w3.org/2001/04/xmldsig-more#rsa-sha256.

The problem here is that this signature algorithm is not supported by the core .NET framework (http://blogs.msdn.com/b/shawnfa/archive/2008/08/25/using-rsacryptoserviceprovider-for-rsa-sha256-signatures.aspx). I found some blog posts on how to activate support for this algorithm, but it did not really work out for me.

So after I failed trying to adjust the code of the SP application to fit WIF, I had a look at the other side of the pipe: my Identity Provider implemented using WIF:

I did not tell WIF to use RSA-SHA256 as signature algorithm anywhere and my X.509 certificate also used RSA-SHA1. So obviously this algorithm must be set somewhere inside of WIF as default value. And indeed it is: If you do not explicitly specify the signature algorithm when calling a constructor of the X509SigningCredentials it is set to RSA-SHA256 by default:

public X509SigningCredentials(X509Certificate2 certificate, SecurityKeyIdentifier ski) 
    : this(
        new X509SecurityToken(certificate), 
        ski, 
        "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", 
        "http://www.w3.org/2001/04/xmlenc#sha256")
{
}

So the solution to this problem is to use another constructor of the X509SigningCredentials class on setting the SigningCredentials of the SecurityTokenService.

An example:

this.SigningCredentials = new X509SigningCredentials(
    certificate,
    "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
    "http://www.w3.org/2000/09/xmldsig#sha1");

Another issue I was facing on manually validating the xml signature of a security token is that the default SignedXml class was not able to find the Id element of the security token. The following article did the trick for me: http://blogs.msdn.com/b/shawnfa/archive/2004/04/05/108098.aspx

WIF in depth: What’s a SecurityKeyIdentifierClause

Windows Identity Foundation (WIF) is a powerful framework for implementing a federated (i.e. distributed) authentication and authorization scheme into your application. It is fairly easy to use with already existing security token services (STS) like Windows Azure Access Control Services (ACS) or the Active Directory Federation Services 2.0 (ADFS 2.0), but when it comes to implementing your own STS it gets really tricky.

The first part – creating the SecurityTokenService class – is covered by several tutorials and blog posts on the web and the WIF SDK from Microsoft also contains a Visual Studio project template for this task. But when it comes to creating your own SecurityTokenHandler (required for custom security token formats) your pretty much on your own.

In this post I am gone explain what the purpose of the classes SecurityKey, SecurityKeyIdentifier and SecurityKeyIdentifierClause in the context of your own SecurityToken implementation is.

To understand the full concept of these SecurityKey concerned classes you have to be aware that there are several types of SecurityTokens. What is commonly referred to as security token are so called “Bearer Tokens” (carrying information with them, e.g. like claims). But a SecurityToken could for example also be a wrapped X.509 certificate (see also the other post about the IssuerNameRegistry).

SecurityKey

As the name already suggests a SecurityKey is just a “security key” for cryptographic operations (like signing or encrypting security tokens). This could be a X.509 certificate, a rsa key (pair) or anything similar. Returning a collection of SecurityKeys is required on a class inheriting from SecurityToken, but usually you just don’t care about security keys in your custom bearer SecurityToken implementation and return an empty, read-only list:

public override ReadOnlyCollection<SecurityKey> SecurityKeys 
{ 
    get { return new List<SecurityKey>().AsReadOnly(); }
}

SecurityKeyIdentifierClause

A SeurityKeyIdentifierClause is something like the unique identifier of a security key. It is used to reference a specific token (or security key) without including the whole content of the token.

You most probably stumble upon this the first time when implementing the CreateSecurityTokenReference method of your custom SecurityTokenHandler class.

As this method is called during issuing tokens and a SecurityTokenIdentifierClause is expected as return value, you have to take care of the logic behind it.

For Saml tokens the CreateSecurityTokenReference() implementation looks like the following:

public override SecurityKeyIdentifierClause CreateSecurityTokenReference(SecurityToken token, bool attached)
{
    if (token == null)
        throw new ArgumentNullException("token");

    return token.CreateKeyIdentifierClause<SamlAssertionKeyIdentifierClause>();
}

Purpose of a SecurityKeyIdentifierClause is to compare tokens. Therefore it has a Matches(object keyIdentifierClause) method. This method is used by a SecurityTokenResolver to return the corresponding SecurityToken for the specified SecurityKeyIdentifierClause.

Summing all this up: a SecurityKeyIdentifierClause is an identifier with some logic to compare equality with other SecurityKeyIdentifierClause objects. So the best implementation for your custom bearer SecurityToken is most probably to use the LocalIdKeyIdentifierClause with the id of your token as localId parameter.

SecurityKeyIdentifier

A SecurityKeyIdentifier is simply a collection of SecurityKeyIdentifierClauses. When ever needed you can use the implementation in System.IdentityModel.Tokens here. There is usually no need to take care of this by your self.

WIF in depth: Validating a security token against an IssuerNameRegistry

The Windows Identity Foundation (WIF) provides an IssuerNameRegistry for validating the issuer of a security token. There are multiple implementations of the abstract class IssuerNameRegistry. ConfigurationBasedIssuerNameRegistry is probably the most commonly used one. You can add trusted issuers to this implementation by adding them in the respective section of your web.config file.

The method GetIssuerName of the IssuerNameRegistry (which is responsible for validating issuers) expects a SecurityToken as parameter and returns the name of the issuer (if valid) or null. Internally the paramter is casted to a X509SecurityToken and the thumbprint of the corresponding certificate is looked up in the list of registered trusted issuers.

This sounds pretty simple and straight forward, but the actual question that came to my mind is: how to obtain the thumbprint of the issuer, as it does not seem to be included in the security token?

It took me some time of research and reading through decompiled framework code, but finally I “discovered” a solution in the SAML2 implementation inside WIF:

Validating signatures of incoming security tokens inside WIF is usually done with an EnvelopedSignatureReader. After reading and validating the xml signature this reader provides the SigningCredentials of the signature:

var root = XElement.Load(wrappedSignatureReader);
var signingCredentials = wrappedSignatureReader.SigningCredentials;

When the security token was signed with a X509 certificate (that’s the most common way), the SigningCredentials are of type X509SigningCredentials and contain somehow a reference to the used certificate.

You can obtain a reference to this certificate by using a X509CertificateStoreTokenResolver. This SecurityTokenResolver is usually present in the property SecurityTokenServiceConfiguration.IssuerTokenResolver (i.e. through your service configuration).

To resolve the SigningCredentials to a X509SecurityToken simply pass the SigningKeyIdentifier to the method TryResolveToken of the IssuerTokenResolver:

protected virtual bool TryResolveIssuerToken(SigningCredentials signingCredentials, SecurityTokenResolver issuerResolver, out SecurityToken token)
{
    if (signingCredentials != null && signingCredentials.SigningKeyIdentifier != null && issuerResolver != null)
    {
        return issuerResolver.TryResolveToken(signingCredentials.SigningKeyIdentifier, out token);
    }

    token = null;

    return false;
}

All this fragments come together in the ReadToken method of your custom SecurityTokenHandler:

protected override SecurityToken ReadToken(XmlReader reader)
{
    using (var wrappedSignatureReader = new EnvelopedSignatureReader(reader, this, this.Configuration.IssuerTokenResolver, true, true, false))
    {
        var root = XElement.Load(wrappedSignatureReader);
        var signingCredentials = wrappedSignatureReader.SigningCredentials;

        SecurityToken issuerToken;
        this.TryResolveIssuerToken(signingCredentials, this.Configuration.IssuerTokenResolver, out issuerToken);

        SecurityToken token;

        // create and fill your custom security token with data here...

        return token;
    }
}

The obtained SecurityToken is of type X509SecurityToken, which can be used to verify the issuer with an IssuerNameRegistry. This is/should be done in the ValidateToken method of your SecurityTokenHandler.