From the Rough Cut
From the Rough Cut
From the Rough Cut
Authorization
When it comes to secure access to your OData endpoints, WCF Data Services invents nothing new; any of the authentication techniques that you want to use for HTTP (and HTTPS) are completely supported by Data Services and are ignored by the OData protocol altogether. That said, there is really no explicit support in Data Services beyond what’s already in WCF to make the integration of authentication any easier.
For example, out of the box, Internet Information Service 7.0 (IIS7) supports add-ins for NTLM and Basic authentication, both of which are standard HTTP authorization protocols and both of which are supported directly in major browsers (I’m sure you’ve see IE pop up a login dialog – that’s what that is). However, the IIS7 implementations of these protocols use the Windows login procedure on the server machine, which works just fine for the intranet, but usually isn’t what folks want on the internet. On the internet, people generally want to manage their own database of users or let someone else on the internet manage it for them. You’ve see sites with HTML forms for logging into a web site, known as “forms authorization” and you’ve seen links that say things like “Login with Google” or “Login with Facebook,” which is known as “federated authorization.”
And we’re not done yet – the internet community is avidly defining and building new authorization protocols all the time. Someday I’m sure we’ll nail it, but in the meantime, OData and Data Services support them all, as does IIS7 and ASP.NET 4.0, assuming you’re willing to write the necessary code.
The magnitude of authorization protocols and how to plug them into IIS7 or ASP.NET is largely outside the scope of this book[22]. However, what I’m going to show you is the bare minimum needed to get it working inside a .NET 4.0, MVC 2 project which can serve as a springboard for your most excellent custom Open Data Federated Authentication Protocol[23] work in the future.
We’re going to implement and use the standard HTTP Basic authentication protocol in this sample because a) it will give you a flavor for how all such protocols work and b) it’s simple enough that even I can understand it. The Basic protocol is very basic indeed:
- The server looks for a request header named “Authentication” with a value consisting of the word “Basic” following by a base64-encoded[24] user name, password pair separated by a colon, e.g. “Basic QmlsbDpwdw==” contains “Bill:pw”.
- If the Authentication header isn’t present or isn’t in the correct format, the server sends back a response header called “WWW-Authenticate” with the value “Basic realm="something"”, e.g. “Basic realm="TinyLinkService"” and a response status code of 401 (meaning “unauthorized”). The client is supposed to use this information to provide credentials using the specified protocol and attempt the request again, e.g. a browser will pop up a dialog box. A custom application can do whatever it likes, e.g. dig in its set of credentials for a match or even send the WWW-Authenticate header along without being asked (the latter is obviously the polite thing to do).
I should note that a good server will work via the Secure Sockets Layer (SSL) and HTTP- Secure (HTTPS) so that a user’s credentials aren’t transmitted over the wire in plaintext, but that’s neither here nor there as far as the Basic protocol, OData, Data Services or we are concerned.
)
Figure 15: The HTTP Basic authentication protocol
Now, before we look at our Basic protocol implementation, the first thing we have to do is turn off forms authentication that comes out of the box for MVC 2 applications in Visual Studio 2010. You can do that by commenting out the <authentication> element in your web.config as Figure 16 shows.
)
Figure 16: Turning off ASP.NET forms authentication
The forms authentication that comes out of the box complete with a user database and the web pages to administer it is great for web sites, but it’s hard to write client programs against[25]. The reason we need to turn this off is because ASP.NET will notice if we return a 401 error and automatically redirect to its forms authentication system, which we don’t want.
Now, with all that warm up, I can show you a simple implementation of server-side Basic authentication suitable for sample use in Data Services:
// Use HTTP Basic authentication
string GetCurrentUser() {
string authorization = HttpContext.Current.Request.Headers["Authorization"];
if (string.IsNullOrEmpty(authorization)) { return null; }
if (!authorization.StartsWith("Basic")) { return null; }
// Pull out the user/password seperated by ':' and Base64 encoded
byte[] base64 = Convert.FromBase64String(authorization.Substring(6));
string[] userpw = Encoding.ASCII.GetString(base64).Split(':');
if (userpw.Length != 2) { return null; }
// TODO: checking the user name/password would be good here...
string user = userpw[0];
string password = userpw[1];
return user;
}
Notice that our implementation cracks the Authorization header, checks for Basic, decodes the base64-encoded string and splits out the user name and password. It doesn’t actually check the resultant credentials against a known good database, but that would be a good idea in your non-sample applications[26].
If there is no user name/password pair according to the Basic authorization protocol, we ask for the client to provide it:
// Request Basic authentication
void RequestLogin() {
HttpContext.Current.Response.AddHeader(
"WWW-Authenticate", "Basic realm=\"TinyLinkService\"");
throw new DataServiceException(401, "Unauthorized");
}
Here, we’re setting the WWW-Authenticate header and then using the DataServiceException to set the HTTP status code and description. The use of the DataServiceException is handy as it will pack enough extra information into the HTTP payload to allow knowledgeable clients, like the .NET Data Services client, to unpack it on the client side and turn it into a more meaningful exception. And even in the face of unknowledgeable clients, the extra information is still available on the wire and is useful when debugging a new service or a broken interaction between the client and service.
If we now invoke our query for links on the browser, it knows to ask for credentials, as Figure 17 shows.
)
Figure 17: The browser-provided Basic authentication login dialog
On the client-side in our sample, it’s simply a matter of populating the Authorization header when a request is made so that the service has the credentials it needs:
var service =
new TinyLinkContainer(new Uri(@"http://localhost:1677/TinyLinkService.svc"));
service.SendingRequest += delegate(object sender, SendingRequestEventArgs e) {
var userpw = "Bill" + ":" + "pw";
var base64 = Convert.ToBase64String(Encoding.ASCII.GetBytes(userpw));
e.Request.Headers.Add("Authorization", "Basic " + base64);
};
foreach (var link in service.TinyLinks) {
Console.WriteLine("Url= {0}, IsActive= {1}, User.Name= {2}",
link.Url, link.IsActive, link.User == null ? "<none>" : link.User.Name);
}
Notice the use of the SendingRequest event so whenever a new request is sent, we add the properly encoded Basic Authorization header before the server even has to ask. If you like, you can configure the service reference to only provide the credentials if asked:
var service =
new TinyLinkContainer(new Uri(@"http://localhost:1677/TinyLinkService.svc"));
// Set the user/password for our queries in case the service asks
service.Credentials = new NetworkCredential("Bill", "pw");
Either way works for providing the credentials to the service, but I prefer to avoid the extra 401 round-trip when I can[27].
Footnotes
[22] On the other hand, Alex James, a Program Manager on the WCF Data Services team, has written a lovely series of blog posts on this topic: http://blogs.msdn.com/b/astoriateam/archive/tags/authentication (http://tinysells.com/149).
[23] ODFAP © 2010. All rights reserved. Some assembly required. Void where prohibited.
[24] Base64 encoding: http://en.wikipedia.org/wiki/Base64 (http://tinysells.com/150).
[25] However, the unstoppable Alex James doesn’t let that dissuade him from teaching you how in part 7 of his series: http://blogs.msdn.com/b/astoriateam/archive/2010/07/21/odata-and-authentication-part-7-forms-authentication.aspx (http://tinysells.com/151).
[26] In fact, I use Basic authentication over SSL/HTTPS on the real-life sellsbrothers.com to expose a secure OData endpoint. It’s simple, but it works, too.
[27] As of this writing, a service throwing a DataServiceException with a 401 and SaveChanges(Batch) don’t all work together in .NET 4.0, which is another reason to prefer pre-populating the Authorization header when making a call. You can read all about it here: http://sellsbrothers.com/Posts/Details/12697 (http://tinysells.com/152).