With fabrik (my portfolio and blogging startup) only weeks away from launch I'm excited to start blogging about "how we did it".
As we're dog-fooding our own API (or "consuming it" if you don't get that expression) one of the big technical challenges was how to handle authentication.
I wanted to keep our web applications as first class citizens of the API so connecting to our auth database directly was a big no no. When I first started building the API I implemented OAuth but soon realized that the protocol was overkill for our needs (we only need Authentication not delegated Authorization).
It was working on my OAuth implementation that let me to the great work by the guys at Thinktecture, in particularThinktecture.IdentityModel. In short, if you need to do anything concerning identity and access control on the .NET stack, you'll probably find it in this library.
One thing included in this library is an authentication handler for ASP.NET Web API that supports many authentication types. One of these is support for session token authentication - a JSON Web Token (JWT) that can be used to achieve cookieless sessions with ASP.NET Web API.
Configuring the AuthenticationHandler is just a matter of creating an AuthenticationConfiguration and adding the authentication types your require:
private static void ConfigureAuth(HttpConfiguration config)
{
var authConfig = new AuthenticationConfiguration
{
DefaultAuthenticationScheme = "Basic",
EnableSessionToken = true,
SendWwwAuthenticateResponseHeader = true,
RequireSsl = false // only for testing
};
authConfig.AddBasicAuthentication((username, password) =>
{
return username == "admin" && password == "password";
});
config.MessageHandlers.Add(new AuthenticationHandler(authConfig));
}
Note the EnableSessionToken setting. It is this that enables session token support.
Requesting a session token
To request a session token we need to make an authenticated request to the "/token" endpoint.
GET http://localhost:65104/token HTTP/1.1
User-Agent: Fiddler
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
Host: localhost:65104
Here we are using Basic authentication. If authentication is successful we will be returned a JSON Web Token like so (shortened for brevity):
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjEz...",
"expires_in": 36000.0
}
This token is signed by the server so that it may be validated in subsequent requests.
Note that the signing key is re-created each time your application starts so if you're in a server farm scenario you may to provide your own key:
var authConfig = new AuthenticationConfiguration
{
DefaultAuthenticationScheme = "Basic",
EnableSessionToken = true, // default lifetime is 10 hours
SessionToken = new SessionTokenConfiguration
{
SigningKey = Constants.SessionTokenSigningKey
}
};
Now that we have a session token we can use it to authenticate requests:
GET http://localhost:65104/contacts HTTP/1.1
User-Agent: Fiddler
Authorization: Session eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjEz...
Host: localhost:65104
Accept: application/json
With this in place we can configure our Web Client (in this case ASP.NET MVC) to use the API to authenticate a user log in. It's as simple as making a request to "/token" with the provided user credentials:
[HttpPost, ValidateAntiForgeryToken]
public async Task<ActionResult> LogIn(UsersLogInModel model)
{
if (!ModelState.IsValid)
{
return View();
}
using (var httpClient = new HttpClient())
{
httpClient.BaseAddress = new Uri(Constants.ApiBaseUri);
httpClient.SetBasicAuthentication(model.Username, model.Password);
var response = await httpClient.GetAsync("token");
if (response.IsSuccessStatusCode)
{
var tokenResponse = await response.Content.ReadAsStringAsync();
var json = JObject.Parse(tokenResponse);
var token = json["access_token"].ToString();
Session[Constants.SessionTokenKey] = token;
FormsAuthentication.SetAuthCookie(model.Username, createPersistentCookie: true);
return Redirect("~/");
}
else // could check specific error code here
{
ModelState.AddModelError("", "The username and password provided do not match any accounts on record.");
return View();
}
}
}
If the request is successful we parse the token from the response and store it in a session (you may need something a little more persistent). If the response is not successful then we assume the credentials are incorrect - of course this isn't necessarily the case (your server may have died) in which case you'd probably want to check the specific status code (401 if authentication failed).
The great thing about this approach is we've not had to store the user's credentials - it's like a simple man's version of the OAuth password grant flow.
One thing you'll have to watch out for is session token expiry. The easiest way round this is to ensure that your forms authentication cookie expires before the token (which defaults to 10 hours).
There's also the possibility (if using ASP.NET session to store your token) that your cookie may outlive your ASP.NET session, for example, if the web application restarts. We handle this with a global action filter that checks if the user is authenticated and whether a token exists (logging them out if not).
Authenticating JavaScript clients
When I first created the fabrik "dashboard" it was a typical data entry style application. This meant that all API access was done using via my controllers - something that the new async/await syntax in C# 5 and asynchronous controller actions in MVC4 made very easy indeed.
However as we started to focus on the user experience we began pushing more behavior into the client, usingKnockoutJS to build our UI - this meant making AJAX requests.
At first I was proxying everything via the MVC app like so:
[HttpPost]
public async Task<ActionResult> Move(int id, int position)
{
await portfolioClient.MoveProjectAsync(Customer.CurrentSite, new MoveProjectCommand
{
ProjectId = id,
Position = position
});
return Json(true);
}
As I started to do this more and more I realized this was just a pointless abstraction and if anything made my life harder.
What would be much better was if we could just call our API directly from JavaScript.
Enter CORS
CORS (short for Cross-Origin resource sharing) essentially provides a way to make AJAX requests to another domain. I'm not going to go into much more detail than that as you can read more here.
It requires two things:
- A client (browser) that supports making CORS requests.
- A server that issues the necessary Access-Control-* headers (and can handle pre-flight requests if neccessary).
If you need to handle more than GET/POST requests in addition to other headers (such as Authorization) you'll need to configure your server to respond to pre-flight requests. This is an OPTIONS request made by the browser to determine what is "allowed" by your server and where from. An example request and response can be seen below:
Request:
Access-Control-Request-Headers:accept, authorization, origin
Access-Control-Request-Method:GET
Host:localhost:65104
Origin:http://localhost:65306
Referer:http://localhost:65306/
Response:
Access-Control-Allow-Headers:accept,origin,authorization
Access-Control-Allow-Origin:*
Adding CORS support to ASP.NET Web API
Adding basic CORS support is pretty easy, using a simple message handler to response to OPTIONS requests and add the necessary headers. However, fine grained control requires more work but yet again you don't have to do this thanks to the guys at Thinktecture. You can read more on Brock Allen's introductory post.
Brock has created a nice fluent interface for configuring CORS - here's what I'm using to allow all origins, methods and request headers.
private static void ConfigureCors(HttpConfiguration config)
{
var corsConfig = new WebApiCorsConfiguration();
config.MessageHandlers.Add(new CorsMessageHandler(corsConfig, config));
corsConfig
.ForAllOrigins()
.AllowAllMethods()
.AllowAllRequestHeaders();
}
Putting it all together
Now that we've enabled CORS on the server we can make requests to our API directly from the browser.
The one missing piece is how we handle authentication. As discussed earlier we have access to a session token that can be used to authenticate requests. How can we make this available in the browser?
The solution I came up with was to generate a dynamic script using an MVC action that sets the token:
public class AssetsController : Controller
{
public ActionResult ApiAuth()
{
var token = Session[Constants.SessionTokenKey] as string;
var script = @"var my = my || {}; my.authToken = '" + token + "'; my.baseUri = '" + Constants.ApiBaseUri + "';";
return JavaScript(script);
}
}
This is then rendered in my layout page like so:
@if (Request.IsAuthenticated) { @Scripts.Render("~/assets/apiauth") }
I then created a simple wrapper client to make the API requests and set the appropriate authentication headers:
my.ApiClient = function (config) {
var authToken = config.authToken,
baseUri = config.baseUri,
configureRequest = function (xhr) {
xhr.setRequestHeader("Authorization", "Session " + authToken);
};
this.createUri = function (path) {
return baseUri + "/" + path;
};
this.get = function (path, query) {
return $.ajax({
url: this.createUri(path),
type: "GET",
beforeSend: configureRequest
});
};
this.post = function (path, data) {
return $.ajax({
url: this.createUri(path),
type: "POST",
contentType: "application/json",
dataType: "json",
data: data,
beforeSend: configureRequest
});
};
this.put = function (path, data) {
return $.ajax({
url: this.createUri(path),
type: "PUT",
contentType: "application/json",
dataType: "json",
data: data,
beforeSend: configureRequest
});
};
this.delete = function (path) {
return $.ajax({
url: this.createUri(path),
type: "DELETE",
dataType: "json",
beforeSend: configureRequest
});
}
};
We can initialize the client like so, passing in the auth token and base URI that was set by our MVC script:
<script>
(function () {
var apiClient = new my.ApiClient({
baseUri: my.baseUri,
authToken: my.authToken,
onAuthFail: function () {
$(".error").show();
}
});
var vm = new my.ContactsViewModel(apiClient);
ko.applyBindings(vm);
vm.refresh();
})();
</script>
To prove that everything works as expected I've created a little sample application on GitHub, aptly namedApiDogFood.
You need to make sure both projects are set to start and after logging in (username: admin, password: password) you should be able to add, update or remove (specifically GET, PUT, POST and DELETE) from your browser.
Enjoy!