In the .NET Framework 4.0 version of WCF, managing multiple asynchronous operations, for example in the form of WCF and HTTP request/response operations, is currently very complex regardless of whether you use the existing event or Begin/End asynchronous pattern. The amount of code needed to facilitate even simple coordination tasks is large and prone to bugs handling errors and timeouts. Yet there are some common communication oriented scenarios that require managing multiple outstanding asynchronous operations:
Execute multiple async operations in parallel and continue when they are all done (either successfully, failed, or timed out).
Execute sequence of async operations, stopping if one of the operations fails or times out.
Nest multiple async operations (first do A, then take result and feed to B etc.).
Combine async operations with timers for easy polling at regular intervals.
The task-based asynchronous programming model first introduced in the .NET Framework 4.0 provides a simple abstraction for the definition, coordination, and management of these operations. As such, providing a first-class asynchronous development experience using tasks should make the above scenarios much simpler to realize.
In order to create an asynchronous service operation, the service developer need only define a service operation that returns an instance of either Task or Task<T>. The decision on whether to return Task or Task<T> depends on whether or not the service operation returns a value. For operations which specify void, Task should be retuned. For service operations that return a value, Task<T> should be retuned.
For task-based methods, if the OperationContractAttribute specifies a name, the name will be used as is. If no name is specified on the OperationContractAttribute, the method name will be used. If the method name terminates with the string “Async”, “Async” will be truncated from the method name and the resulting string will be used as the operation name. This is to avoid having a method like “FooAsyncAsync” on the client after proxy code generation.
If a service like the one below is written, an InvalidOperationException will be thrown because the task-based method has the same name as the sync and async methods. As a result, a service of the type below would not be supported.
The following illustrates use of a task-basd asynchronous service operation which in turns calls out asynchronously to 2 external services, waits for both services to return, then calculates and returns a value based on the return values of the 2 external services.
This service operation leverages the Task.WhenAll combinator in order to wait for the completion of both asynchronous external service calls in a manner that does not block the thread of execution. The C# 5 async and await keywords are then used to return identify the service operation as asynchronous and define the operation which adds the product unit price and the shipping price as a continuation.
After proxy generation, calling the service looks boringly good:
As I talked about at the end of my AppFabric TV interview, I use a tool called ScrumPig to manage my personal workflow (one day, I would love to try it out across an entire team, but baby steps). Recently, ScrumPig 2 was released, and added a very handy new feature for something that was becoming more than just a slight annoyance for me. To give you a better idea of what I’m talking about check out a snapshot of my backlog.
The problem here is all of the items with the green diamond. These represent completed items – and as time progresses, they (hopefully) multiply in numbers. And while looking at such a view should make me feel super-good about myself, instead it just creates a bunch of clutter that keeps me from clearly seeing the next things that I need to work on. Fortunately, ScrumPig 2 added a rich search syntax – and while I’m not going to blog the entire help doc on the subject, the following excerpt enables me to easily see just want I’m interested in:
General Syntax
text Matches the item name “text” Matches the item name #number Matches the item number +term Must match -term Must not match
Tasks
<p> Matches the pending state <i> Matches the in progress state <c> Matches the completed state <b> Matches the blocked state <x> Matches the cut state
As such, by simply entering -<c> in the search box, I get a view of all backlog items that are not completed.
Recently, Pedro Félix sent me some questions on an internal mailing list regarding the recent sample I pushed out for integrating OAuth 2 into Web API (if you haven’t checked out Pedro’s blog, you should go and do that). I thought they were really good questions/comments, so I wanted to share them here, along with my responses, and invite you into the conversation. Some of the “Qs” are comments, but in the name of keeping the format simple, I’ve just broadly adopted the Q/A format.
Q
Regarding the “A Brief Disclaimer” section, OAuth’s primary goal is delegated *authorization* on resource access. IMHO, your scenario fits well into this goal. The key observation is that the *resource* under access control is the *user’s identity*. Instead of the user *pushing* its identity to the service (e.g. Basic authentication or a federation protocol such as SAML), the service *pulls* this identity (just a resource from the OAuth view point) from a trusted-third party (Facebook).
A
I agree that it fits – However, I don’t yet believe that treating an OAuth resource server role as an identity provider “fits well” for 2 main reasons:
It seems wasteful to establish an OAuth session (using “session” since an access token as valid – and as such must be stored on the authZ or resource server) so that it can be used just long enough to get a piece of identity information. For that scenario, the push model of federated identity tokens seems like a better fit.
Because OAuth is really an authorization protocol, and because the major players like Facebook act as both the authZ server and the resource server role, every application that wants to have Facebook authenticate its users (each “relying party”) needs to register a pho Facebook application with its own app key and secret – or use a broker like ACS that does this for you and sends you an identity token. Again, doable, but feels to me like a misuse of OAuth.
Q
I’m unable to fit this scenario into any of the typical OAuth use cases/profiles. Typically, the OAuth client
is a webapp interacting with the user via a browser
is an active client running on the user’s machine
In this scenario, the OAuth client is a web service, being accessed by a service client on the user’s machine:
A
The scenario is a modification of a standard OAuth server flow. Web API is the OAuth client, Facebook is the AuthZ and resource server. Web API fits into the definition of a confidential client here and as such, I’m using an auth code grant type. Where this breaks off from the more typical OAuth flow (which would generally be a Web application) is in the fact that the UX is a single page, AJAX-driven app, so there’s an additional protocol (term used loosely) happening between the jQuery code and the Web API.
Q
IMHO, it would be better to start with simpler scenarios
web api as a resource server, using an external authz server (e.g. AppFabric’s ACS)
web api as an authz server, using various grant_type (password, client_credentials, saml,…)
A
I called those out at the bottom of the post and these are the scenarios that I’m working through now – For people unfamiliar with the world of federated identity, though, I would argue that they are not inherently simpler scenarios.
Q
On OAuthFacebookOpHandler, I don’t think that attaching the principal to the current thread is a good idea on this brave new world of asynchrony – the underlying thread may change several times. A better solution would
Attach the principal to the current request message (the threads may change on a request, but the request message doesn’t)
Return the principal as an http parameter, so that it can be used as an input parameter on downstream handlers and on operations
Yesterday, I wrote an HttpModule to support enabling Http basic authentication for Web APIs running in an ASP.NET host. But wait, you say – IIS already supports basic authentication?!? This is true…kind of. Basic authentication is supported, but only if the credentials being sent across in Http basic can be resolved to Windows credentials – which IMHO seems like a scenario where I would just use integrated Windows authentication – but that’s beside the point. The point is that I want to support the Http basic flow and validate the credentials using my own credential store. This has been well documented, so I’m not going to repeat all of that detail here, but I do want to tell you about one thing that tripped me up.
Part of my logic reads like this. “If anonymous access is enabled, then you don’t need to bother processing any further.” This means that I need to find out whether anonymous access is enabled or disabled. Now, this isn’t a problem if I’m configuring authentication in my local Web.config, but in my case, I’m setting this on my Web site (custom host) in the IIS management console.
When I configure at the site level, the configuration information is added to the applicationHost.config file
Cool – so I just need to access this information in my HttpModule and figure out if anonymous authentication is turned on – should be simple. The problem I ran into was that there are multiple ways that look like they should accomplish this task (and one does if you do some other stuff), but only 1 way seems to work they way I expected.
I started out by trying to access config from the current HttpContext
var x = currentContext.GetSection(
"system.webServer/security/authentication/anonymousAuthentication");
anonymousEnabled = (bool)x["enabled"];
That didn’t work – it was always null, though it would work if I set the values in my local config file.
So I tried the sledge hammer approach using the IIS admin api
using(var serverManager = new ServerManager()) {
var config = serverManager.GetApplicationHostConfiguration();
var anonymousSection = config.GetSection(
"system.webServer/security/authentication/anonymousAuthentication",
"basic.test.local");
anonymousEnabled = (bool)anonymousSection["enabled"];
}
This approach actually did give me the value that I wanted, but there were a couple problems with the approach
It required me to give my app domain read permissions to %windir%\system32\inetsvr\config – and that just feels wrong on multiple levels
It required me to declare my site name – which seems pretty brittle
What I really wanted was a single API that will project the consolidated configuration information from my local Web.config all the way up to my applicationHost.config – I mean, at the end of the day, IIS needs this information, so certainly it’s exposed somewhere, right?
Yes
var y = WebConfigurationManager.GetSection(
"system.webServer/security/authentication/anonymousAuthentication");
anonymousEnabled = (bool)y["enabled"];
If you already knew this, awesome – I wish you had been around to help me. If you didn’t know this, hope it helps.
This week I’ll be pushing a sample to the WebAPI-Prototype branch in our Codeplex repository for doing an OAuth 2.0 dance for Web APIs. Before I get into how the sample works, let’s quickly define some OAuth 2.0 terms (note that these are all defined in the OAuth 2.0 spec, but I’m defining them here so that you don’t need to read the spec as a prerequisite for this blog post).
Some Context
Resource owner – represents the entity who actually owns the protected resources. In the case of this sample, the user (e.g. – you) is the resource owner.
Client – represents the application which accesses a resource owner’s protected resources after the resource owner has explicitly granted it permission – this last part can also be said, “after the resource owner has authorized the client to his/her protected resources”.
Resource Server – represents the application that is responsible for hosting the resource owner’s protected resource. The resource server uses access tokens when processing and responding to requests for protected resources.
Authorization Server – represents the application that is responsible for authenticating a resource owner, enabling the resource owner to authorize a client, and ultimately issuing an access token to the client.
As the OAuth 2.0 spec defines, the abstract flow appears really simple:
However, in practice, nothing is ever as simple as the abstract flow makes it seems (that’s probably why they call it “abstract”). For each of the stages of this flow, there are multiple ways of accomplishing the stage. In this post, I’m going to discuss one way of implementing the OAuth 2.0 flow, but know that this represents only 1 of several possible options. Moving forward, I plan on adding more flows into the prototype branch (and of course, blogging about them here).
A Brief Disclaimer
I’m a big believer in the principle of “the right tool for the right job” – and as I’m building out this prototype, one of the thoughts I keep arriving at is that while OAuth gives you authentication as a byproduct of having the resource owner authorize a client to a resource server, the focus of OAuth seems much more on authorization than it does federated identity. I think that what I’m getting at is in the difference between delegated authorization and federated identity, but I’m having a hard time getting to a crisp, non-philosophical articulation of the differences between those 2 terms. Judging from a quick Google search, I’m not the only one having trouble coming up with a clean articulation of the differences (I suspect this is because authN is always required at some point to do authZ).
At any rate, you may end up asking yourself a similar question as we go through the discussion of the sample, so I wanted to be up front in saying that I feel the same sense of weirdness and am also actively investigating OAuth patterns that use a federated identity system for authN and OAuth for authZ (or patterns to simply make it easier to integrate with federated identity systems, if simply not managing credentials is really the thing you care about).
The OAuth 2.0 Sample Workflow
For the sample, the goal was to secure a Web API using Facebook’s OAuth 2.0 capabilities so that the Web API didn’t need to maintain any usernames or passwords. The resulting workflow looks like the following:
As you can see right off the bat, the concrete example is a good bit more complex than the abstract flow defined by the OAuth 2.0 spec. Why is that? As I see it, there are 2 primary drivers of the added complexity to the end-to-end flow. First, I decided that my Web API represents my OAuth client. This means that once authorized by the resource owner (e.g. user), my Web API can get resources directly from the resource server (e.g. Facebook) without having to expose that data to the resource owner, or any malicious application pretending to be the resource owner. However, because the end user experience is still a browser, and because my browser experience is AJAX-based (meaning that I can’t count on the browser to act directly on 302 status codes), I need a mini-protocol between my Web API and my AJAX code.
The second reason for the added complexity relates a bit to the “brief disclaimer” above. That is, this workflow takes advantage of the fact that authentication is required for authorization – and my Web API client does call into Facebook (in its resource server role) to get some resource owner data. However, the Facebook access token is used by my Web API only long enough to get a piece of user-identifying data which it then plugs into an existing authorization store – I’ve faked out the ASP.NET membership provider in this case.
I’ll be writing another post on my general thoughts here, but for now, this workflow works (even with the additional complexity) and should set the stage for showing how AuthN/AuthZ can work for Web API.
Plugging into Web API
One of the goals I had for the prototype was to enable the auth mechanism to plug into Web API using the standard extensibility points. Additionally, I wanted it to use the standard AuthorizeAttribute that MVC uses. As such, I took advantage of 2 Web API extensibility hooks: operation handlers and message handlers. Additionally, there’s some logic behind wiring everything up that I encapsulated into an extension method that works with the HttpConfiguration object.
First, we have the OAuthFacebookOperationHandler. The responsibility of this operation handler is to examine the incoming request to see whether the operation being called needs to be protected and if so, determine whether the user has been authorized (currently making this determination using a cookie). Based on whether or not the user has been authorized for the operation, the handler will either pass control over to the operation or return a standard Http challenge response containing the Facebook OAuth authorization dialog URL.
First, I’m sure you’ll notice that there’s a bunch of todo notes still in the code. I’m actively working on getting this more seamlessly plugged into things like the membership provider, the AuthorizeAttribute, and the forms authentication cookie generator. However, the purpose of this post is to show the mechanics of initiating an OAuth flow, so hopefully those unfinished aspects won’t be too big of a distraction. But that aside, the basic workflow looks like this:
check to see whether the user has already gone through the OAuth dance, been authenticated, and has authorized the Web API. If this process has happened, there will be a cookie in the request
If the user has been authenticated, authorize the user based on the AuthorizeAttribute on the service operation
If the user has not been authenticated, throw a 401 challenge response with a scheme of OAuth and a location parameter of the Facebook auth dialog
In my sample, I have an AJAX client, so the following jQuery is able to take the challenge response, parse out the location and popup the Facebook auth dialog…
Like I said, this jQuery uses a regex to get the value of the location parameter in the response. It then uses that to open the Facebook auth dialog. The user will then interact with Facebook to authenticate and then authorize my Web API to a Facebook application that I created (note: you’ll need to create register an application with Facebook to use its OAuth authorization server endpoints). If you look back at the URL that’s passed to the location header (line 45 of the operation handler), you’ll notice that one of the query values is the redirect URI. My operation handler will always generate a value that is the address of the originally requested resource with an additional path segment called “authtoken”. Therefore, if my resource is localhost/comments, the redirect URL will be localhost/comments/authtoken (this isn’t a requirement of any kind – it was just how I put this code together). The thing is, I don’t have a resource or service named authtoken. So how does this get picked up? Enter the OAuthFacebookMessageHandler.
If you remember from Glenn’s post about Web API extensibility, message handlers give you an opportunity to plug in down in the channel stack and work directly with HttpRequestMessage and HttpResponseMessage. And while this isn’t terribly helpful if you need details about the operation (parameters, return values, etc.), it’s great if you need only work at the Http level – and it’s very fast! In my case, I need to basically capture all requests that have authtoken as the last path segment, get some information about the user from Facebook so that I can correlate that with my local authorization store (e.g. membership provider) and then drop a cookie that can be used in subsequent requests.
As you would expect, this code takes in an HttpRequestMessage. However, because it’s task-based, it needs to return a Task<HttpResponseMessage> rather than just an HttpResponseMessage. With async operation handlers, the basic principles are as follows:
To continue the flow of execution to the inner message handler and ultimately up through the service operation, call base.SendAsync(..) . If you want to do some processing on the response side only, after the operation has been called, call base.SendAsync, but then add a ContinueWith(..) call.
To short circuit all further processing of the request and simply return a response, return your own Task<HttpResponseMessage> using Task.Factory.StartNew(..)
Because there is no actual service operation for /authtoken, I’m really dealing purely at the Http layer, so I’ll just be returning a new task rather than allowing the incoming message to propagate – and within my request processing I’m doing the following things:
Exchange the auth code returned to me from Facebook for an access token – this is the thing that is actually used to access Facebook data
Use the access token to get my username
Drop my username to a cookie so that my operation handler can pick it up on subsequent calls (note: don’t EVER, EVER, EVER actually do this in production – I’m trying to show you the mechanics of the OAuth dance, and only that)
Emit some script to close the popup window
If all is successful, this handler will set future calls up for success, then signal the parent window to both close the popup and retry the newly-authorized request, so that while there’s a lot of moving parts here, it feels pretty seamless for the end user.
Finally, there’s the question around how all of this gets wired up. I extracted the configuration code into a single, more simple extension method:
This means that I can register for OAuth with code similar to:
There are a bunch of identity and auth related scenarios that I’m currently prototyping, in addition to cleaning up some of the hard-coded stuff in this one. Here’s how I’ve currently prioritized security-related scenario investigations:
Ensure that Http basic over SSL works without any issues
Web API as an AuthN + AuthZ + Resource server – this would make the Web API equivalent to a service like Twitter where you could enable users to authorize 3rd party applications to your Web API (along with manage the permissions of those applications) – the key here is that Web API would have manage its own credential store.
Web API as an AuthZ + Resource server – this is similar to the previous with the notable exception that Web API would rely on a federated identity provider for AuthN. In this scenario, we would integrate with an STS (or broker like ACS).
Do these look like the right scenarios? The right ordering? As with everything else, I welcome your feedback!
