Dan looks after Web API: as you can imagine, we\u2019ve been discussing Web API security often in the last few months. The latest subject was custom Authorization Servers: he mentioned that some of his customers really want to be able to control in fine details what resources can be accessed, what kind of permissions are possible, and similar considerations. Basically, he wanted to build a custom AS.
My classic knee-jerk reaction was the same I have when talking about development of a custom STS: \u201cyou are better off using a packaged product or a hosted service\u201d. An AS, like an STS, is on the critical path of pretty much everything you do; it has to be available, manageable, secure, performing\u2026 and those are features that are expensive to obtain: whomever built the packaged product\/service already paid those prices, why should you re-do it, and so on. If you read this blog in the last few years, you already know that song.<\/p>\n
However, just like for the custom STS cases, there are indeed situations where the custom route \u2013 albeit steep \u2013 is the only one that offers the level of control required.
That made me think of some examples. For a GIS service the resources could be maps of a region, information layers (such as points of interests, yearly temperature data, median income of the population), routes and similar; the permissions could be very specific, such as the ability of reading the artifacts referring to one area but not another; or to see all the maps for all regions, but no access to PII-rich data layers. That would indeed require an AS which is awfully close to the resources themselves, knows everything about the resource types and is aware of all the possible operations to authorize or prevent. <\/p>\n
That convinced me that trying to write an AS, even if very simple, would be a worthwhile experimentation. I knew that my wife was going to work this Sunday and that I would have had time on my hands, hence I promised Dan I would put something together. Well, here we are \ud83d\ude42 <\/p>\n
Here there\u2019s the plan:<\/p>\n
- \n
- I\u2019ll put together a simple Windows Store app, consuming an (even simpler) Web API without any authentication. <\/li>\n
- I\u2019’ll write a MVC4 application, adding in a controller the MINIMAL logic for processing OAuth2 token requests and generating responses, according to the implicit profile. I\u2019ll secure the app using the identity and access tools and ACS, which will allow us to use Facebook and Windows Azure AD users. Finally, I\u2019ll deploy the AS to Windows Azure Web Sites.<\/li>\n
- I\u2019ll modify the Windows Store app client to obtain a token from the AS and use it to secure calls to the Web API service; <\/li>\n
- I\u2019ll also modify the Web API to validate incoming tokens <\/li>\n<\/ul>\n
You\u2019ll see that the code is surprisingly simple, but don\u2019t get fooled into thinking that any of this can go \u2018as is\u2019 anywhere near to production! Just like for custom STSes, it\u2019s easy to put together something that goes through the protocol motions; but before even considering moving it further, there is an enormous amount of critical aspects to be addressed. As usual, please read all this with a humongous grain of salt. Think Superman\u2019s Fortress of Solitude<\/a>-class.<\/p>\n
Sample client and Web API\u2019s Protected Resource<\/h1>\n
Alrighty, let\u2019s get our hands dirty! \ud83d\ude42 I won\u2019t give you exact step by step instructions or the Sunday won’t be enough to write the post, but this should be detailed enough for you to follow if you are familiar with Visual Studio.<\/p>\n
Let\u2019s start with the service side. I want to create a simple inspirational quotes service. Here I will just support the classic IEnumerable GET of all the resources, but you can happily add editing capabilities later and implement the matching HTTP verbs afterwards.
Create a new Web Application project, choose MVC 4 Web App, and pick the Web API template. I called my project MyProtectedResource.
Add a new controller for serving the quotes. Here there\u2019s the code of the one I wrote:<\/p>\nusing<\/span> System.Collections.Generic;\nusing<\/span> System.Web.Http;\n\nnamespace<\/span> MyProtectedResource.Controllers\n{\n public<\/span> class<\/span> InspiringQuotesController : ApiController\n {\n \/\/<\/span>\n \/\/ GET: \/InspiringQuotes\/<\/span>\n\n private<\/span> static<\/span> readonly<\/span> List<string<\/span>> Quotes = new<\/span> List<string<\/span>>\n {\n ""data is not information""<\/span>,\n ""correlation is not causation""<\/span>,\n ""Something, something, something, dark side. Something, something, something, complete""<\/span>,\n };\n\n \n public<\/span> IEnumerable<string<\/span>> Get()\n {\n return<\/span> Quotes;\n }\n }\n}<\/pre>\nAs straightforward as it gets. Let\u2019s move to the client.<\/p>\n
Add a new project to the solution: choose the Windows Store category, and create an empty application.<\/p>\n
Here I want to show a pretty Spartan UX: a title, a list of quotes (I\u2019ll data-bind) and a button to retrieve them. I could retrieve them at startup time, but I want the button to show you few interesting things about how authentication in Windows Store apps works later in the post. Here there\u2019s the XAML:<\/p>\n
<<\/span>Page<\/span>\n x:Class<\/span>="App1.MainPage"<\/span>\n xmlns<\/span>="http:\/\/schemas.microsoft.com\/winfx\/2006\/xaml\/presentation"<\/span>\n xmlns:x<\/span>="http:\/\/schemas.microsoft.com\/winfx\/2006\/xaml"<\/span>\n xmlns:local<\/span>="using:App1"<\/span>\n xmlns:d<\/span>="http:\/\/schemas.microsoft.com\/expression\/blend\/2008"<\/span>\n xmlns:mc<\/span>="http:\/\/schemas.openxmlformats.org\/markup-compatibility\/2006"<\/span>\n mc:Ignorable<\/span>="d"<\/span>><\/span>\n\n<<\/span>Grid<\/span> Background<\/span>="{StaticResource ApplicationPageBackgroundThemeBrush}"<\/span>><\/span>\n \n<<\/span>StackPanel<\/span> Orientation<\/span>="Vertical"<\/span>><\/span>\n <<\/span>TextBlock<\/span> Text<\/span>="Inspiring Quotes"<\/span> \n Margin<\/span>="50,50,0,50"<\/span> \n Style<\/span>="{StaticResource PageHeaderTextStyle}"<\/span> \/><\/span>\n <<\/span>Button<\/span> Click<\/span>="Button_Click_1"<\/span> Margin<\/span>="50,0,0,50"<\/span>><\/span>get quotes...<\/<\/span>Button<\/span>><\/span>\n <<\/span>ListView<\/span> x:Name<\/span>="quotesListView"<\/span>><\/span>\n <<\/span>ListView.ItemTemplate<\/span>><\/span>\n <<\/span>DataTemplate<\/span>><\/span>\n <<\/span>Grid<\/span>><\/span>\n <<\/span>Border<\/span>><\/span>\n <<\/span>TextBlock<\/span> Text<\/span>="{Binding}"<\/span> \n FontSize<\/span>="18"<\/span> FontFamily<\/span>="Lucida Handwriting"<\/span> Margin<\/span>="50,50,0,50"<\/span>\/><\/span>\n <\/<\/span>Border<\/span>><\/span>\n <\/<\/span>Grid<\/span>><\/span>\n <\/<\/span>DataTemplate<\/span>><\/span>\n <\/<\/span>ListView.ItemTemplate<\/span>><\/span>\n <\/<\/span>ListView<\/span>><\/span>\n<\/<\/span>StackPanel<\/span>><\/span>\n<\/<\/span>Grid<\/span>><\/span>\n<\/<\/span>Page<\/span>><\/span>\n<\/pre>\nYes, my XAML skills are pretty primitive \ud83d\ude42 but this will do.<\/p>\n
As you can see, the button is already wired up with one click event (i didn\u2019t even bother to rename the one that VS generated for me when I double clicked on the button in the designer). Let\u2019s take a look at its code.<\/p>\n
\n1: <\/span>private<\/span> async void<\/span> InitializeQuotes()<\/pre>\n2: <\/span>{<\/pre>\n3: <\/span> ObservableCollection<string<\/span>> quotesColl = null<\/span>;<\/pre>\n4: <\/span> <\/pre>\n5: <\/span> using<\/span> (var http = new<\/span> HttpClient())<\/pre>\n6: <\/span> {<\/pre>\n7: <\/span> HttpResponseMessage response = <\/pre>\nawait http.GetAsync(new<\/span> Uri("http:\/\/localhost:47524\/Api\/InspiringQuotes"<\/span>));<\/pre>\n8: <\/span> Stream rez = await response.Content.ReadAsStreamAsync();<\/pre>\n9: <\/span> var deser = new<\/span> DataContractJsonSerializer(typeof<\/span>(List<string<\/span>>));<\/pre>\n10: <\/span> quotesColl = <\/pre>\nnew<\/span> ObservableCollection<string<\/span>>((IEnumerable<string<\/span>>)deser.ReadObject(rez));<\/pre>\n11: <\/span> quotesListView.ItemsSource = quotesColl;<\/pre>\n12: <\/span> }<\/pre>\n13: <\/span>}<\/pre>\n14: <\/span> <\/pre>\n15: <\/span>private<\/span> async void<\/span> Button_Click_1(object<\/span> sender, RoutedEventArgs e)<\/pre>\n16: <\/span>{<\/pre>\n17: <\/span> InitializeQuotes();<\/pre>\n18: <\/span>}<\/pre>\n<\/div>\nIf you are familiar with Windows Store apps, that will be very straightforward; but in case you aren\u2019t<\/p>\n
- \n
- Line 3: this collection will contain the list of quotes and be used as data source. I am using that type because that will allow you, if you choose to add editing capabilities, to propagate the changes back to the service using the WinRT environment\u2019s features. Feel free to ignore this last bit, it\u2019s irrelevant to this tutorial <\/li>\n
- Line 5: creates an HttpClient for hitting the service with our request<\/li>\n
- Line 7: hits the service with our request. The IIS express address is what I got from the property pages. I should have used HTTPS, of course.<\/li>\n
- Lines 8 to 11: parses the response into our quotes collection. Note the complete absence of error management code, due to my slacking attitude during weekends<\/li>\n
- Line 17: the actual call<\/li>\n<\/ul>\n
Simple, right? let\u2019s give it a spin. Go in the solution properties, make the solution multi-start, and pick both projects. Hit F5. <\/p>\n
![\"image\"](\"http:\/\/cloudidentity.com\/blog\/wp-content\/uploads\/2013\/02\/1256.image_5F00_3E29D8A6.png\" "\\"image\\"")
<\/a> <\/p>\nHit \u201cget quotes\u201d\u2026<\/p>\n
![\"image\"](\"http:\/\/cloudidentity.com\/blog\/wp-content\/uploads\/2013\/02\/0412.image_5F00_0BC60527.png\" "\\"image\\"")
<\/a> <\/p>\n\u2026and like a fierce lighthouse piercing through the thick fog of confusion, three immortal quotes are revealed.<\/p>\n
Great! Now, let\u2019s say that we want to restrict access to this service to specific user populations. From all the JWT samples, we already know we can easily secure the Web API side. How to acquire a token from the Windows Store app, though? Windows provides nice API for that: but in order to use them, we need an Authorization Server.<\/p>\n
A micro authorization server<\/h1>\n
Did you read the OAuth2 specification? I am totally serious, it is actually pretty readable! OAuth2 describes how a client can work with one entity called Authorization Server (from now on AS) to obtain delegated access to a protected resource. I won\u2019t go in the details of how that works here; rather, I\u2019ll discuss what I implemented and why. As usual, I\u2019ll do some pretty dramatic simplifications; also, per what I wrote here<\/a> I won\u2019t even try to be \u201cinteroperable\u201d (whatever that means in this context<\/a>).<\/p>\n
In a nutshell, the job of an AS is to <\/p>\n
- \n
- establish the identity of the caller (to verify that he\/she actually is the resource owner)<\/li>\n
- accept requests formed according to what the OAuth2 specs describe<\/li>\n
- inform the caller about the permissions being asked, from which client and for what resources; ask for consent<\/li>\n
- if the caller granted consent, return the kind of grant asked (code, token, etc etc) according to what the OAuth2 specs describe<\/li>\n<\/ol>\n
That\u2019s very similar to what you\u2019d do when implementing a passive STS: pretty much any web application will do. Good, I decided: I am going to use an MVC4 app for implementing the AS.
\n
If you want to follow along, create a new MVC4 application in the solution: I called mine PoorMansAS. Any template will do: I picked the Intranet one simply because there\u2019s not too much stuff out of the box to clean up. <\/p>\nNow, let\u2019s go through the various tasks listed above and see how to project those in our implementation.<\/p>\n
#1 is the step where people often gets confused. I believe this stems from the fact that this step entails securing the authorization endpoint with some kind of sign-in flow, which can (and often is) done with perfectly standard, traditional sign in methods: ASP.NET membership provider, OpenID provider, federation with ADFSv2, federation with an ACS namespace, Windows Azure AD\u2026 any method will work, as long as the AS can use its outcome to recognize the resource owner. The IdP used for sign-in can be in itself entirely oblivious about what will happen next (e.g. the actual OAuth bits).
\n
For our AS I am going to use ACS. Concretely: I\u2019ll use the Identity and Access Tools for VS2012 to secure the MVC app against one ACS namespace. I am going to use one I already have, which happens to be already federated with Facebook and Windows Azure AD; you can find all the instructions here<\/a>. <\/p>\n#2 is pretty easy, especially if we pick an easy profile: here I\u2019ll go for the implicit profile, where a request directly leads to an access token without intermediate steps. Here there\u2019s how the spec describes a request for the implicit flow:<\/p>\n
GET \/authorize?response_type<\/font>=token&client_id<\/font>=s6BhdRkqt3&state<\/font>=xyz <\/p>\n
&redirect_uri<\/font>=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP\/1.1 <\/p>\n
Host: server.example.com<\/font><\/p>\n
That boils down to a controller and one action accepting the above as parameters. Hence, I\u2019ll create a new controller as one action as below:<\/p>\n
namespace<\/span> PoorMansAS.Controllers\n{\n public<\/span> class<\/span> AuthorizationServerController : Controller\n {\n [Authorize]\n public<\/span> ActionResult Authorize(string<\/span> response_type,\n string<\/span> client_id,\n string<\/span> state,\n string<\/span> redirect_uri,\n string<\/span> resource)\n { <\/pre>\nYou might have noticed I have added an extra parameter, resource. Its purpose is to let the AS know which resource we are asking access to. That will likely trigger some controversy about use of Scope for that purpose instead. I don\u2019t want to enter in religious arguments here, if you are interested in the rationale we can chat offline; let\u2019s just say that for the purpose of this example (which is NOT production ready, as you already know) the resource parameter makes up of an easier flow.<\/p>\n
#3 is the step that I am going to leave in its entirety as exercise for the reader. It entails looking up the current user (which you\u2019ll find in ClaimsPrincipal.Current, as authenticated from ACS and WIF in #1), comparing it with the resources model that is specific to your case, render some UI which prompts the user for the things you want to ask, and get back here with the results (and without having forgotten the list of parameters you originally received). That\u2019s pure MVC UX, no OAuth magic required, hence I\u2019ll skip it.<\/p>\n
#4 is the interesting part. It mainly entails creating the token you want to return to the client, and embed it in the right format. Per the OAuth spec, it should look like the following:<\/p>\n
HTTP\/1.1 302 Found
\n
Location: http:\/\/example.com\/cb#access_token<\/font>=2YotnFZFEjr1zCsicMWpAA <\/p>\n&state<\/font>=xyz&token_type<\/font>=example&expires_in<\/font>=3600<\/font><\/p>\n
That\u2019s right, this is just a redirect against the redirect_uri specified in the request (which you should normally validate against what you know about the client, BTW). This means we can just generate a token, embed it in the right URL template, return it within a RedirectResult and call it a day. Sounds simple enough. Let\u2019s get to work and write the body of Authorize.<\/p>\n
Given that we are skipping #3, what should we put in the token? I have a proposal. How about we take the claims content of the incoming token (the one we get from #1) and just re-issue those? For the tutorial that seems good enough; if you want to apply sophisticated transformation logic without repackaging, that\u2019s pretty simple: do whatever claims arithmetic you want on the incoming ClaimsPrincipal before using it to seed the outgoing token.
\n
Speaking of the outgoing token: the obvious choice here is a JWT, hence make sure you add a reference to the JWT Handler NuGet<\/a>. The good news is that creating a new JWT is ridiculously easy with the new JWT handler, we don\u2019t even need to bother setting up with an STS pipeline; we can literally just new() one, with the parameters we want. So, here there\u2019s the first line of our Authorize method:<\/p>\n\n1: <\/span>JWTSecurityToken jst = new<\/span> JWTSecurityToken("urn:poormansas"<\/span>,<\/pre>\n2: <\/span> resource, <\/pre>\n3: <\/span> ClaimsPrincipal.Current.Claims, <\/pre>\n4: <\/span> CreateSigningCredentials(), <\/pre>\n5: <\/span> DateTime.Now, <\/pre>\n6: <\/span> DateTime.Now.AddHours(1));<\/pre>\n<\/div>\nI broke the parameters down so that I can provide some commentary.<\/p>\n
Line 1: this string is the Issuer identifier I picked for our micro AS.<\/p>\n
Line 2: that\u2019s the resource ID: basically it\u2019s the token audience, the service we are issuing a token for<\/p>\n
Line 3: the claims describing the current authenticated user<\/p>\n
Line 4: the key used by the AS to sign the token. More about that below<\/p>\n
Line 5: creation instant<\/p>\n
Line 6: validity limits. This token will be valid for one hour, starting from now.<\/p>\n
Now we have a token in memory. Superb! All we need to do is serialize it and return it as described by the standard. Here there are the next (and last) 2 lines of Authorize.<\/p>\n
\n1: <\/span>JWTSecurityTokenHandler jh = new<\/span> JWTSecurityTokenHandler();<\/pre>\n2: <\/span> <\/pre>\n3: <\/span>return<\/span> new<\/span> RedirectResult(<\/pre>\n4: <\/span> string<\/span>.Format("{0}#access_token={1}{2}&token_type=bearer&expires_in=3600"<\/span>, <\/pre>\n5: <\/span> redirect_uri, <\/pre>\n6: <\/span> jh.WriteToken(jst), <\/pre>\n7: <\/span> ((state ==