Katana has no middleware to turn SSL client certificates into a ClaimsIdentity. And since I am currently collecting material for my upcoming Web API security course I used the opportunity to experiment with Katana authentication middleware.
There’s a certain pattern you have to follow for integrating into the Katana security model. It all starts with a class that configures the authentication mechanism – the so called options:
public class ClientCertificateAuthenticationOptions : AuthenticationOptions
{
public X509CertificateValidator Validator { get; set; }
public bool CreateExtendedClaimSet { get; set; }
public ClientCertificateAuthenticationOptions() : base(“X.509”)
{
Validator = X509CertificateValidator.ChainTrust;
CreateExtendedClaimSet = false;
}
}
You have to derive from AuthenticationOptions and set your default authentication type – that’s just a string and can be changed by the user of your middleware. You further expose whatever customization make sense for you – in my case the certificate validator and an indicator if you want a minimal or a full claim set.
The real work is done in a so called authentication handler – again there is base class to derive from. You typically need to implement AuthenticateCoreAsync (credential validation) and ApplyResponseChallengeAsync (challenge generation). Client certificates don’t really have an HTTP challenge – so I skipped this method. There are other methods that you can override when you need initialization and cleanup features (InitializeCoreAsync and TeardownCoreAsync).
In the authentication logic, you inspect the incoming credential and – if present – turn it into a ClaimsIdentity. This identity in turn gets wrapped into an authentication ticket which allows to couple the identity with additional properties that are not claims. –
public class ClientCertificateAuthenticationHandler :
AuthenticationHandler<ClientCertificateAuthenticationOptions>
{
protected override Task<AuthenticationTicket> AuthenticateCoreAsync()
{
var cert = Context.Get<X509Certificate2>(“ssl.ClientCertificate”);
if (cert == null)
{
return Task.FromResult<AuthenticationTicket>(null);
}
try
{
Options.Validator.Validate(cert);
}
catch
{
return Task.FromResult<AuthenticationTicket>(null);
}
var claims = GetClaimsFromCertificate(
cert, cert.Issuer, Options.CreateExtendedClaimSet);
var identity = new ClaimsIdentity(Options.AuthenticationType);
identity.AddClaims(claims);
var ticket = new AuthenticationTicket(
identity, new AuthenticationProperties());
return Task.FromResult<AuthenticationTicket>(ticket);
}
}
The glue between the handler, lifetime management, configuration and the Katana pipeline is the Katana authentication middleware. It’s responsibility is to create the handler, transfer the options and call the corresponding methods on the handler at the right point in time:
public class ClientCertificateAuthenticationMiddleware :
AuthenticationMiddleware<ClientCertificateAuthenticationOptions>
{
public ClientCertificateAuthenticationMiddleware(
OwinMiddleware next,
ClientCertificateAuthenticationOptions options)
: base(next, options)
{ }
protected override AuthenticationHandler<ClientCertificateAuthenticationOptions> CreateHandler()
{
return new ClientCertificateAuthenticationHandler();
}
}
…and with a bit of extension method syntactic sugar – you end up here:
app.UseClientCertificateAuthentication();
app.UseWebApi(WebApiConfig.Register());
The claims describing the client certificate can then be retrieved either using the OwinContext or Web API specific using the RequestContext.
Filed under: IdentityModel, Katana, OWIN, WebAPI
