ASP.NET Web API - Screencast series Part 6: Authorization

We're concluding a six part series on ASP.NET Web API that accompanies the getting started screencast series. This is an introductory screencast series that walks through from File / New Project to some more advanced scenarios like Custom Validation and Authorization. The screencast videos are all short (3-5 minutes) and the sample code for the series is both available for download and browsable online. I did the screencasts, but the samples were written by the ASP.NET Web API team.

In Part 1 we looked at what ASP.NET Web API is, why you'd care, did the File / New Project thing, and did some basic HTTP testing using browser F12 developer tools.

In Part 2 we started to build up a sample that returns data from a repository in JSON format via GET methods.

In Part 3, we modified data on the server using DELETE and POST methods.

In Part 4, we extended on our simple querying methods form Part 2, adding in support for paging and querying.

In Part 5, we added support for Data Annotation based validation using an Action Filter.

In Part 6, we'll require authentication using the built-in Authorization Filter.

[Video and code on the ASP.NET site]

Requiring Authorization using the Authorization Filter

In Part 5, we use a custom Global Action Filter to enforce validation on every Action. In this (final) part, we'll use the built-in Authorize Filter. As with other Filters, they can be applied at the Action, Controller, or Global levels. In this case, we'll add it at the controller level by adding the AuthorizationFilter attribute.

[Authorize] 
public class CommentsController : ApiController  
{ 
    ...
}

That's it from the server side. If a client makes an unauthorized request, the AuthorizationFilter does the only thing that makes sense for an HTTP API - it returns an HTTP Status Code 401, Authorization Required. Again, we're back to the value of using HTTP for an API - we don't need to arrange anything, any client on any platform will know what an HTTP 401 response means.

Handling Redirection on the Client

Many websites (and web frameworks) handle authorization by doing a server-side redirection to a login page. I wrote an in-depth post about how ASP.NET MVC handles authorization redirection - internally an HttpUnauthorizedResult (HTTP 401) is intercepted by the FormsAuthenticationModule, which redirects to Login URL specified in web.config.

None of that makes sense from an HTTP API perspective, though. HTTP API's return HTTP Responses to clients, which include things like Status Codes, Response Body, and Headers. It's up to the client to decide what to do when they get a 401. In this JavaScript / browser based sample, we'll just redirect to the login page on the client.

$(function () { 
    $("#getCommentsFormsAuth").click(function () { 
        viewModel.comments([]); 
        $.ajax({ url: "/api/comments", 
            accepts: "application/json", 
            cache: false, 
            statusCode: { 
                200: function(data) { 
                    viewModel.comments(data); 
                }, 
                401: function(jqXHR, textStatus, errorThrown) { 
                    self.location = '/Account/Login/'; 
                } 
            } 
        }); 
    }); 
});

In this case, logging in gives you a valid forms auth cookie, so your next request will pass authorization.

What about other validation scenarios?

If you want to do something different with validation in an ASP.NET Web API controller, usually the best approach is to create a custom Authorization Filter which derives from the base AuthorizationFilterAttribute and overrides the OnAuthorization method. Here a few blog posts showing how to extend authentication in ASP.NET Web API:

On the client, it's up to you. You may want to show a login form in a desktop application, handle things programmatically when accessing the service via code, etc. You'll follow the same pattern, though - handle the HTTP 401 status code and login to the server, either by posting to a login action or following the service's documented login API.

The End... and Where To Next

That wraps up this series. Some ideas of where to go next:

30 Comments

Comments have been disabled for this content.