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.