The world in which we live evolves at a vast speed. Today, many applications on the Internet expose an API which can be consumed by everyone using a web browser or a mobile application on their smartphone or tablet. How would you build your API if you want these apps to be a full-fledged front-end to your service without compromising security? In this article, I’ll dive into that. We’ll be using OAuth2 and the Windows Azure Access Control Service to secure our API yet provide access to all those apps out there.
Kinepolis: veel static content / in-frame caching
A couple of years ago, having a web-based application was enough. Users would navigate to it using their computer’s browser, do their dance and log out again. Nowadays, a web-based application isn’t enough anymore. People have smartphones, tablets and maybe even a refrigerator with Internet access on which applications can run. Applications or “apps”. We’re moving from the web towards apps.
A great example of an API is Twitter. They have a massive data store containing tweets and data related to that. They have user profiles. And a web site. And an API. Are you using www.twitter.com to post tweets? I am using the website, maybe once a year. All other tweets come either from my Windows Phone 7’s Twitter application or through www.hootsuite.com, a third-party Twitter client which provides added value in the form of statistics and scheduling. Both the app on my phone as well as the third-party service are using the Twitter API. By exposing an API, Twitter has created a rich ecosystem which drives their real value: data.
If you want to expose your data and services to external third-parties, you may want to think about building an API. Having an API gives you a giant advantage on the Internet nowadays. Having an API will allow your web application to reach more users. App developers will jump onto your API and build their app around it. Other websites or apps will integrate with your services by consuming your API. The only thing you have to do is expose a valuable, managed and supported API and get people to know it. Apps will come. Integration will come.
The mainidea of API’s is tobroadenyourreach. Youcan’tcreateappsthatcanbeused on every fridge out there, it’s way toocostly. But ifyou have a valuable service which is supported, peoplewillbuildappsaround it. Andifitmakes sense toanyonetocreate a fridge app on top of your API, itwill happen.
You’renot the onlyone. Thenumber of API’s is growing at a fast pace and the number of appsandmashups on different devicesgrowswiththat. Ifyou want market share, your best chance of growingit is in building a valuable API.
An API is simply a software-to-software interface, defined by whoever is exposing the API to public or private users. It defines constraints, both technical as well as legal. Twitter for example defines a usage constraint: if you are using their API without paying you will be limited to a certain number or requests.
Modern web API’s are built around the HTTP protocol. HTTP is the protocol you use daily to navigate the Internet. This makes it easy to expose your API: the Internet has the infrastructure ready to access your API and expose it on the web. Here’s an example HTTP request to www.google.com:GET http://www.google.com/ HTTP/1.1User-Agent: FiddlerAccept: text/html, */*Host: www.google.comGoogle responds to this request with the HTML page you all know and use. There are two very interesting concepts in this request: the HTTP verb (in this case: GET) and the Accept header (in this case text/html, */*). Both define what the client wants from the server: GET tells the server to simply send data as a response, text/html, */* tells the server that the response should preferably be in the HTML format, but optionally any other format will work for the client too. We can inform the server of what we intend to do using one of the standard HTTP verbs:GET – return dataHEAD – check if the data exists but don’t return itPOST – create or update dataPUT – put dataMERGE – merge values with existing dataDELETE – delete dataThere are more verbs if you like, but these are the most widely used. Let’s have a look at Google’s response as well: HTTP/1.1 302 FoundLocation: http://www.google.be/Cache-Control: privateContent-Type: text/html; charset=UTF-8Content-Length: 218 <HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8"><TITLE>302 Moved</TITLE></HEAD><BODY><H1>302 Moved</H1>The document has moved<A HREF="http://www.google.be/">here</A>.</BODY></HTML> Interesting here is the first line: Google responds with a 302 status code. 302 means that the server has found the data you are looking for but that the URL you’ve used to access it was wrong or has changed. The server also responds with a Location header, telling you where to find the actual resource you were trying to access. There’s a large number possible status codes you can use. Here are some you will most commonly encounter:200 OK – Everything is OK, your expected data is in the response.401 Unauthorized – You either have to log in or you are not allowed to access the resource.404 Not Found – The resource could not be found.500 Internal Server Error – The server failed processing your request.See the theme? 1XX are informational. 2XX codes mean “successful”. 3XXX tell you to go elsewhere, like our 302 example above. 4XX means the client has done something wrong. A wrong address or a wrong request. 5XX means the server has had a problem, like the feared error 500 – Internal Server Error you see on some websites.
We can inform the server of what we intend to do using one of the standard HTTP verbs. There are more verbs if you like, but these are the most widely used.
There’s a large number possible status codes you can use. Here are some you will most commonly encounter:200 OK – Everything is OK, your expected data is in the response.401 Unauthorized – You either have to log in or you are not allowed to access the resource.404 Not Found – The resource could not be found.500 Internal Server Error – The server failed processing your request.See the theme? 1XX are informational. 2XX codes mean “successful”. 3XXX tell you to go elsewhere, like our 302 example above. 4XX means the client has done something wrong. A wrong address or a wrong request. 5XX means the server has had a problem, like the feared error 500 – Internal Server Error you see on some websites.
Be detailed! Usegood status code responses. 201 CREATED is probablybetterthanjust 200 OK whencreating a new entity.+ demo Fiddleragainst HTCPCP deployment out there
Here are four basic conventions for ASP.NET Web API:Requests have an HTTP verb defined. This maps to the API controller’s action method.Requests have an Accept header. This is handled by ASP.NET Web API’s MediaTypeFormatter and will transform the request to your controller from JSON, XML or whatever format you want to add as a MediaTypeFormatter.Responses have an HTTP status code.Responses are formatted by ASP.NET Web API’s MediaTypeFormatter into JSON, XML or whatever format you want to add as a MediaTypeFormatter.
Quick demo: show howtocreate a simple APIwith a GET and POST method. Maybe show routing andan action filter or something. Also show media formatting.
If you decide that your API isn’t public or specific actions can only be done for a certain user (get me my tweets, Twitter!), you’ll be facing authentication and authorization problems. With ASP.NET Web API, this is simple: add an [Authorize] attribute on top of a controller or action method and you’re done, right? When using the out-of-the-box authentication/authorization mechanisms of ASP.NET Web API, you are relying on either forms authentication or Windows authentication. Both require the user to log in. And as your API user isn’t really your user, but an application acting on behalf of a user, that means that the application should know the user’s credentials. Would you give your username and password to a third-party website to access your Twitter account? I don’t think so.
I want you to remember one sentence: “your API user isn’t really your user, but an application acting on behalf of a user”. It has implications. It means you are “delegating” access to an API to a consuming application.
Maybeyouwork at a company which hands out guest badges tovisitors. You have a badge with full access to the office, yourguests have a guest badge. Your name is on that badge: ifanythinggoes wrong or has tobedone, colleaguescanidentify the guest as someonewho’sthere on your call.The guest badge canbelimited in scope (only the 7th foor) or in validityduration (onlytoday).Wouldn’tthisbe a great approach toprotectyour API?
As anexample, take lanyrd.com. They keep track of conferences you’llbespeaking at and conferences thepeopleyou follow on Twitter are speaking at. To get that data, theyneed access to the list of peopleyou follow on Twitter. Here’swhathappens:You want to log in on Lanyrd, theyredirectyoutoTwitter’s login page. Notice the token in the address bar: itidentifies the callingapplicationtoTwitter.You log in on Twitterandgive consent with a limited scope: Lanyrdwillbeabletoseeyourtimelineand get the list of peopleyou follow. The scope is limitedtothat: Lanyrdcan’ttweet on mybehalf. Theycan’tfavoritetweets. Or sendmessages. Or do anythingelse.Twitterredirects me back toLanyrd, posting back a “refresh” tokenWhatyoudon’tsee:Lanyrdusesthat token torequestan “access token” fromTwitter.Twitter checks the validity of the incoming token and checks the origin, to make sure no otherapplication but Lanyrdcomes in withthat token.Whenvalid, Twitter returns an access token toLanyrd, containing:An access keyA new refresh tokenThe allowed scopeValiditydurationA signature- When the token expires, Lanyrduses the new refresh token to go throughthisprocessagain.
There’s a lot toimplement.
One of the interesting components in the Windows Azure platform is the Access Control Service (ACS). ACS allows you to outsource your authentication and authorization woes and have Microsoft handle those. At www.myget.org, an application me and a colleague have been working on, you’ll find that you can log in through a variety of identity providers (Windows Live ID, Google, Facebook, GitHub, …). We don’t have to do anything for that: ACS solves this and presents us with a set of claims about the user, such as his username on GitHub. If we want to add another identity provider, we simply configure it in ACS and without modifying our code, you can login through that new identity provider.Next to that, ACS provides a little known feature: OAuth2 delegation support. The idea with that is that your application’s only job is to ask the user if a specific application can act on his or her behalf and store that decision in ACS. From then on, the client application will always have to go to ACS to fetch an access token and a refresh token which can be presented to your API.
This approach comes in very handy! Every client application will only have to ask our Authorization server once for user consent, after which ACS will take care of handing out access tokens, expiring tokens, renewing tokens and so on. ACS handles all the authentication and authorization load for us, even with 1 billion apps and users consuming my API. And all of that for just 19 US$ per million actions on ACS (see pricing calculator).
There’s a lot toimplement. Whynot outsource itto Windows Azure ACS?You: OAuthauthorization server youdecidewho is granted access andwho’snot. You’ll have totell ACS aboutthis, but apart fromthatyou have nothingto do.ACS: Keep track of supportedconsumers based on your inputACS: Keep track of user consent based on the user’s inputACS: OAuth token expiration & refresh based on all of the aboveYou: Your API of course!
API’s are the new apps. They can be consumed by everyone using a web browser or a mobile application on their smartphone or tablet. How would you build your API if you want these apps to be a full-fledged front-end to your service without compromising security? In this session, Maarten will explain how to build an API using the ASP.NET Web API framework and how the Windows Azure Access Control service can be used to almost completely outsource all security and OAuth-related tasks.We’re moving from the web towards apps. Next to your website, apps are becoming more and more popular as an alternative manner to consume your data and services. Why not use that as a lever to reach more users? By exposing an API, you’re giving third party app developers the opportunity to interface with your services and at the same time, they are the advocate of them. Embrace them, give them a good API.Of course, that API should be protected. OAuth2 is becoming the de-facto standard for that but requires some server-side coding on your part. If you just want to focus on the API and delegate the heavy lifting and scaling of the OAuth2 protocol, you may as well delegate it to the Windows Azure Access Control Service. WindowsAzure.Acs.Oauth2 will help you with that.
1. SEPTEMBER 25, 2012 | SLIDE 1
2. OAuth-as-a-service using ASP.NET Web API and Windows AzureMaarten Balliauw Access Control@maartenballiauwTechnical Consultant Windows AzureRealDolmenSEPTEMBER 25, 2012 | SLIDE 2
3. Who am I? Maarten Balliauw Antwerp, Belgium www.realdolmen.com Focus on web ASP.NET MVC, Windows Azure, SignalR, ... MVP Windows Azure & ASPInsider http://blog.maartenballiauw.be @maartenballiauw Author: Pro NuGet - http://amzn.to/pronugetSEPTEMBER 25, 2012 | SLIDE 4
4. Agenda Why would I need an API? API characteristics ASP.NET MVC Web API Windows Azure ACSSEPTEMBER 25, 2012 | SLIDE 5
5. WHY WOULD I NEED AN API?SEPTEMBER 25, 2012 | SLIDE 6
6. Consuming the web 2000-2008: Desktop browser 2008-2012: Mobile browser 2008-2012: iPhone and Android apps 2010-2014: Tablets, tablets, tablets 2014-2016: Your fridge (Internet of Things)SEPTEMBER 25, 2012 | SLIDE 7
7. SEPTEMBER 25, 2012 | SLIDE 8
8. Twitter & Facebook By show of hands…SEPTEMBER 25, 2012 | SLIDE 9
9. Make everyone API (as the French say)SEPTEMBER 25, 2012 | SLIDE 10
10. Expose services to 3rd parties Valuable Flexible Managed Supported Have a planSEPTEMBER 25, 2012 | SLIDE 11
11. Reach More ClientsSEPTEMBER 25, 2012 | SLIDE 12
12. You’re not the only one Source: http://blog.programmableweb.com/2012/04/16/open-apis-have-become-an-essential-piece-to-the-startup-model/SEPTEMBER 25, 2012 | SLIDE 13
13. API CHARACTERISTICSSEPTEMBER 25, 2012 | SLIDE 14
14. What is an API? Software-to-Software interface Contract between software and developers Functionalities, constraints (technical / legal) Programming instructions and standards Open services to other software developers (public or private)SEPTEMBER 25, 2012 | SLIDE 15
15. Flavours Transport Message contract HTTP SOAP Sockets XML Binary JSON HTML …SEPTEMBER 25, 2012 | SLIDE 16
16. Technical Most API’s use HTTP and REST extensively Addressing HTTP Verbs Media types HTTP status codesSEPTEMBER 25, 2012 | SLIDE 17
17. Demo The Web is an APISEPTEMBER 25, 2012 | SLIDE 18
18. HTTP Verbs GET – return data HEAD – check if the data exists POST – create or update data PUT – put data MERGE – merge values with existing data DELETE – delete dataSEPTEMBER 25, 2012 | SLIDE 19
19. Status codes 200 OK – Everything is OK, your expected data is in the response. 401 Unauthorized – You either have to log in or you are not allowed to access the resource. 404 Not Found – The resource could not be found. 500 Internal Server Error – The server failed processing your request. …SEPTEMBER 25, 2012 | SLIDE 20
20. Be detailed! Think about RFC 2324 (HTCPCP)SEPTEMBER 25, 2012 | SLIDE 21
21. ASP.NET WEB APISEPTEMBER 25, 2012 | SLIDE 22
22. ASP.NET Web API Part of ASP.NET MVC 4 Framework to build HTTP Services (REST) Solid features Modern HTTP programming model Content negotiation (e.g. xml, json, ...) Query composition (OData query support) Model binding and validation (conversion to .NET objects) Routes Filters (e.g. Validation, exception handling, ...) And more!SEPTEMBER 25, 2012 | SLIDE 23
23. ASP.NET Web API is easy! HTTP Verb = action “Content-type” header = data format in “Accept” header = data format out Return meaningful status codeSEPTEMBER 25, 2012 | SLIDE 24
24. Demo Crafting an API using ASP.NET Web APISEPTEMBER 25, 2012 | SLIDE 25
25. Securing your API No authentication Basic/Windows authentication [Authorize] attribute They all require username/password to be known by the API consumer…SEPTEMBER 25, 2012 | SLIDE 26
26. “your API user isn’t really your user, but an application acting on behalf of a user” (or: API consumer != end user)SEPTEMBER 25, 2012 | SLIDE 27
27. OAUTH2SEPTEMBER 25, 2012 | SLIDE 28
28. Guest badges Your full-access badge Guest badge Your name on it Limited scope (only 7th floor) Limited validity (only today)SEPTEMBER 25, 2012 | SLIDE 29
32. What you have to implement OAuth authorization server Keep track of supported consumers Keep track of user consent OAuth token expiration & refresh Oh, and your APISEPTEMBER 25, 2012 | SLIDE 33
33. Windows Azure ACCESS CONTROL SERVICESEPTEMBER 25, 2012 | SLIDE 34
34. ACS - Identity in Windows Azure Active Directory federation Graph API Web SSO Link apps to identity providers using rules Support WS-Security, WS-Federation, SAML Little known feature: OAuth2 delegationSEPTEMBER 25, 2012 | SLIDE 35
35. OAuth flow using ACSSEPTEMBER 25, 2012 | SLIDE 36
36. Demo (the big one) ASP.NET Web API, OAuth2, Windows Azure ACSSEPTEMBER 25, 2012 | SLIDE 37
37. OAuth2 delegation? You: OAuth authorization server ACS: Keep track of supported consumers ACS: Keep track of user consent ACS: OAuth token expiration & refresh You: Your APISEPTEMBER 25, 2012 | SLIDE 38
38. CONCLUSIONSEPTEMBER 25, 2012 | SLIDE 39
39. Key takeaways API’s are the new apps Valuable HTTP ASP.NET Web API Windows Azure Access Control ServiceSEPTEMBER 25, 2012 | SLIDE 40