In my last post I explained why I think it is important to use the authorization server pattern right from the start. In this post I want to show how to build the possibly simplest authorization server using the new Katana middleware that’s shipping with Web API v2.
The scenario here is very similar to what I called “session tokens” before – the client sends a username/password to a token endpoint, and gets back an access token in return. Afterward the client can use this access token to communicate with the Web API.
The client can “forget” the user’s credentials after the initial token request, and depending on the lifetime of the access token might not have to re-prompt the user for credentials for a reasonable amount of time. By adding refresh tokens in the mix you can also enable other interesting scenarios – but that’s for another post.
We had an implementation for session tokens in Thinktecture.IdentityModel and we were able to layer that feature over arbitrary other authentication mechanisms (but most people used it really in conjunction with Basic Authentication). With the Katana OAuth2 middleware we will use the resource owner flow instead.
Writing an authorization server using Katana revolves around a class that derives from OAuthAuthorizationServerProvider. Here you can override various methods to take control over the OAuth2 protocol details. The minimum requirement though is to validate the incoming client in the ValidateClientAuthentication method..
Side note: when I say ‘client’ – I mean the client in the OAuth2 sense – which is the piece of software making the request [silicon-based lifeform] – not the human aka user of that client [carbon-based lifeform]. OAuth2 defines some mechanisms how the client can transmit credentials to the authorization server – this is really only suitable for certain scenarios – and not applicable to ours here. So we skip it (but will come back later to it).
public override async Task ValidateClientAuthentication
// OAuth2 supports the notion of client authentication
// this is not used here
Since we are technically speaking implementing the OAuth2 resource owner flow – the next method we need to implement is called GrantResourceOwnerCredentials. In this method you need to validate the username and password. If that succeeds, you create a ClaimsIdentity that represents the authenticated user. Any claims you add to this identity will become part of the access token and thus be accessible by the Web API.
Typically the claims you add describe the identity of the user, e.g. his user id (the ‘sub’ claim) or roles he is member of. Don’t go crazy here! The more claims you add, the bigger the token gets – and the token has to be submitted on every request.
public override async Task GrantResourceOwnerCredentials
// validate user credentials (demo!)
// user credentials should be stored securely (salted, iterated, hashed…)
if (context.UserName != context.Password)
// create identity
var id = new ClaimsIdentity(“Embedded”);
id.AddClaim(new Claim(“sub”, context.UserName));
id.AddClaim(new Claim(“role”, “user”));
…and that’s really it for a bare-bones resource owner credentials flow. The next step is to wire up the authorization server to the Katana pipeline. There are two separate pieces of middleware that you need. The authorization server middleware takes care of handling the token request and generation – the bearer token authentication middleware for consuming the token:
public void Configuration(IAppBuilder app)
// token generation
// for demo purposes
AllowInsecureHttp = true,
TokenEndpointPath = new PathString(“/token”),
AccessTokenExpireTimeSpan = TimeSpan.FromHours(8),
Provider = new SimpleAuthorizationServerProvider()
// token consumption
The AccessTokenExpireTimespan property specifies how long the access token should be valid. Keep in mind that there is no built-in way to revoke access tokens once they have been issued. So if you want to disable the user or update claims, that’s the latency you will have. Again refresh tokens can help here (future post).
In the client you need to divide your logic into two parts – request the token (sending credentials) and use the token.
Since requesting the token is using normal OAuth2 resource owner flow, you can use some OAuth2 client or you handcraft the HTTP request yourself (see the spec). Using the Thinktecture.IdentityModel.Client OAuth2Client, this boils down to:
private static TokenResponse GetToken()
var client = new OAuth2Client(
new Uri(“https://localhost:2727/token “));
return client.RequestResourceOwnerPasswordAsync(“bob”, “bob”).Result;
…and using the token could look like this:
private static void CallService(string token)
var client = new HttpClient();
var response = client.GetStringAsync(
new Uri(“http://localhost:2727/api/identity “)).Result;
The full sample can be found here.