Building your own API and Securing it with oAuth 2.0 in ASP.NET WebAPI 2

Objectives:

1. Make a true RESTful Web API (enable CRUD functions by HTTP POST, GET, PUT, and DELETE).
2. Enable Cross-Origin Resource Sharing, i.e., CORS (the accessibility of the API by JavaScript can be controlled).
3. Enable Secure Authorization for API calls (use the OAuth 2.0 authorization framework).
4. Enable Transport Layer Security, i.e., SSL (reject every non-HTTPS request).

Required Tools:

1. A Windows Computer.
2. Microsoft Visual Studio Express 2013 for Web (free download).

Recommended Knowledge:

1. Securing (ASP.NET) Web API based architectures (video).

AND/OR

1. ASP.NET Web API 2 (tutorials).
2. OAuth 2.0 Authorization Framework (specification).
3. Open Web Interface for .NET (OWIN).
4. Writing an OWIN Middleware in the IIS integrated pipeline (tutorial).
5. Enabling Cross-Origin Requests in ASP.NET Web API (tutorial).

An Skeleton Project by ASP.NET Web API 2 (oAuth 2.0 and CORS support)

1. Creating the Project

Create an ASP.NET Web Application (Visual C#) in Microsoft Visual Studio Express 2013 for Web. Let’s name it Skeleton.WebAPI. Select the Web API template and Change Authentication from ‘No Authentication’ to ‘Individual User Accounts’, [screenshot].

The ‘Controllers/ValuesController.cs’ holds our sample API endpoints. Run the project and in the browser go to ‘http://localhost:port/api/values‘ and you should get a 401 Unauthorized.

2. Writing the Sample API Endpoints

In ‘Controllers/ValuesController.cs’, comment out [Authorize] to disable authorization. Run the project and in the browser go to ‘http://localhost:port/api/values‘ and now you should get 2 values.

Change ‘Controllers/ValuesController.cs’ with the following code to enable CRUD operations, [Link]. This controller now accepts HTTP GET, POST, PUT, and DELETE to receive a list of values, add a value, update a value, and delete a value. Currently, these values are stored in the Web Server memory, but ideally they will be saved in the database. I recommend using Repository Pattern for it, [More info].

Let’s write a simple html page to call these api endpoints. For example, the following code can be used for receiving the list of current values:

	$.ajax({
	type: "GET",
	url: 'http://localhost:port/api/values',
	success: function (_d) { alert(JSON.stringify(_d));}
	}).fail(function (_d) { alert(JSON.stringify(_d)); });

view raw

api_tester.js

hosted with ❤ by GitHub

The full list of API calls by JavaScript can be found here. At this point, you will notice that all the API calls are returning errors. That’s because we haven’t added Cross-Origin Resource Sharing (CORS) support to the server.

3. Enabling Cross-Origin Resource Sharing (CORS) support 

To Enable CORS support, first install Microsoft.AspNet.WebApi.Cors by NuGet. Open up ‘App_Start/WebApiConfig.cs’ and add the following line in the Register method:

	public static void Register(HttpConfiguration config)
	{
	config.EnableCors();
	// other stuff
	}

view raw

WebApiConfig.cs

hosted with ❤ by GitHub

Then open your API Controller, ‘Controllers/ValuesController.cs’ and add the following line before the class definition:

	[EnableCors(origins: "*", headers: "*", methods: "*")]
	// [Authorize]
	public class ValuesController : ApiController { /*Class Definition*/}

view raw

ValuesController.cs

hosted with ❤ by GitHub

It tells the server the accept all types requests. You can obviously filter out the requests. For more customization, read this.

4. Cleaning up the Views from the project

You should notice that the VS template created some views in the project. As we are building a pure Web API, there will be no views. So, delete App_Start/[BundleConfig,RouteConfig].cs, Areas/*, Content/*, Controllers/HomeController.cs, fonts/*, Scripts/*, Views/*, Project_Readme.html, and favicon.ico. Finally, remove the following lines from Global.asax.cs:

	RouteConfig.RegisterRoutes(RouteTable.Routes);
	BundleConfig.RegisterBundles(BundleTable.Bundles);

view raw

Global.asax.cs

hosted with ❤ by GitHub

At this point, we have completed Objectives 1 and 2. The code up to this point can be  downloaded from https://github.com/rfaisal/ASPWebAPI_Example_OAuth_CORs/tree/crud_cors_only_v1.

5. Adding oAuth 2.0 support

In the simplest terms, here is how oAuth (or most token based authorization) works. The client request an Access Token from the Authorization Server. The Authorization Server verifies the identity of the client somehow and returns an Access Token, which is valid for a limited time. The client can use the Access Token to request resources from the Resource Server as long as the Access Token is valid. In our case, both Authorization Server and the Resource Server are the same server, but they can be separated easily.

Ideally, you need to write an OWIN Middleware in the IIS integrated pipeline for oAuth. But, the VS template generates the necessary codes for the OWIN Middleware. Watch this video to learn more about these implementations.

Now, we will add 2 more functionality, namely registering a new user and requesting a Access Token based on the username and password.

The user registration controller (Controllers/AccountController.cs) is already generated by the Template. First add the following line in the AccountController to allow CORS:

[EnableCors(origins: "*", headers: "*", methods: "*")]

view raw

AccountController.cs

hosted with ❤ by GitHub

Then you can call the end point http://localhost:port/api/Account/Register/ and HTTP POST an object consisting of UserName, Password, and ConfirmPassword to register an account.

Now, the endpoint for requesting an Access Token is also generated by the template. The code is in App_Start/Startup.Auth.cs :

	//other stuff
	OAuthOptions = new OAuthAuthorizationServerOptions
	{
	TokenEndpointPath = new PathString("/Token"),
	Provider = new ApplicationOAuthProvider(PublicClientId, UserManagerFactory),
	AuthorizeEndpointPath = new PathString("/api/Account/ExternalLogin"),
	AccessTokenExpireTimeSpan = TimeSpan.FromDays(14),
	AllowInsecureHttp = true
	};
	//other stuff

view raw

Startup.Auth.cs

hosted with ❤ by GitHub

It says that the client can request an Access Token by calling http://localhost:port/Token endpoint and HTTP POSTing grant_type, username, and password as Url Encoded String. This endpoint, however, is not an API endpoint. To enable CORS to this endpoint we need to add the following code segment to the ConfigureAuth function of App_Start/Startup.Auth.cs file.

	public void ConfigureAuth(IAppBuilder app)
	{
	//other stuff
	app.Use(async (context, next) =>
	{
	IOwinRequest req = context.Request;
	IOwinResponse res = context.Response;
	if (req.Path.StartsWithSegments(new PathString("/Token")))
	{
	var origin = req.Headers.Get("Origin");
	if (!string.IsNullOrEmpty(origin))
	{
	res.Headers.Set("Access-Control-Allow-Origin", origin);
	}
	if (req.Method == "OPTIONS")
	{
	res.StatusCode = 200;
	res.Headers.AppendCommaSeparatedValues("Access-Control-Allow-Methods", "GET", "POST");
	res.Headers.AppendCommaSeparatedValues("Access-Control-Allow-Headers", "authorization", "content-type");
	return;
	}
	}
	await next();
	});
	//other stuff
	}

view raw

Startup.Auth.cs

hosted with ❤ by GitHub

We are almost done. We have to modify all the API calls to pass this Access Token. First of all, un-comment [Authorize] attribute on the ValuesController and run to make sure that all of the API calls are returning 401 Unauthorized. Add the following property with each ajax call to pass the Access Token as the Bearer Token:

	beforeSend: function (xhr) {
	xhr.setRequestHeader("Authorization", 'Bearer ' + _access_token);
	},

view raw

bearer_token.js

hosted with ❤ by GitHub

At this point, we have completed Objectives 1, 2, and 3. The code up to this point can be  downloaded from https://github.com/rfaisal/ASPWebAPI_Example_OAuth_CORs/tree/crud_cors_oauth.

6. Enforce SSL for all API calls

Any information that is not transferred over SSL is not secure. So, we are going to reject any request that doesn’t come over HTTPS. First we will write a filter that can be used to filter out non-https requests. Here is the code:

	public class RequireHttpsAttribute : AuthorizationFilterAttribute
	{
	public override void OnAuthorization(HttpActionContext actionContext)
	{
	if (actionContext.Request.RequestUri.Scheme != Uri.UriSchemeHttps)
	{
	actionContext.Response = new HttpResponseMessage(System.Net.HttpStatusCode.Forbidden)
	{
	ReasonPhrase = "HTTPS Required"
	};
	}
	else
	{
	base.OnAuthorization(actionContext);
	}
	}
	}

view raw

RequireHttpsAttribute.cs

hosted with ❤ by GitHub

When we add this class to our project, we have [RequireHttps] available. Add this attribute to all the Controller class. For example,

	[RequireHttps]
	[EnableCors(origins: "*", headers: "*", methods: "*")]
	[Authorize]
	[RoutePrefix("api/Account")]
	public class AccountController : ApiController {/*class definition*/}

view raw

AccountController.cs

hosted with ❤ by GitHub

	[RequireHttps]
	[EnableCors(origins: "*", headers: "*", methods: "*")]
	[Authorize]
	public class ValuesController : ApiController {/*class definition*/}

view raw

ValuesController.cs

hosted with ❤ by GitHub

Finally, we also want the Token request to be enforced over HTTPS. To do so, remove ‘AllowInsecureHttp = true’ from Startup.Auth.cs.

	OAuthOptions = new OAuthAuthorizationServerOptions
	{
	//other stuff
	TokenEndpointPath = new PathString("/Token")
	// AllowInsecureHttp = true
	};

view raw

Startup.Auth.cs

hosted with ❤ by GitHub

To test the SSL enforcement, change the SSL Enabled property to true for the Development Server in Visual Studio and use the SSL Url, [screenshot].

The final code can be  downloaded from https://github.com/rfaisal/ASPWebAPI_Example_OAuth_CORs/tree/crud_cors_oauth_ssl.

A screenshot of the client, [screenshot].

Tagged: api, asp-net, authentication, authorization, C-Sharp, code, cors, design patterns, git, github, https, oauth, quality code, restfull, security, source control, ssl, visual-studio, web-api, windows