API Authentication, Authorization, and OAuth
In recent weeks the SAP StreamWork Invocation REST web service API moved from Basic Authentication using HTTPs to using OAuth for authorization of all API calls. Since the move has been puzzling to some of the developers who have worked with the API over the past few months, I thought it would be helpful to talk about some of the reasons behind the move.
If you understand OAuth but you just need help with code see SAP StreamWork OAuth, a code walk through.
While we were using Basic Auth for the API (Still available on beta.12sprints.com until March 15th), it was very simple to authenticate to StreamWork to make API calls. It was easy; you just prompted the end user for their user name and password and submitted them with your first API call which created a session with StreamWork for the rest of your calls. It made a lot of sense and it worked very much like the web interface to StreamWork.
For some people the move was troubling because we were moving from a simple and easy solution to a more complex and hard to implement solution. Why would anyone want to do this?
In today’s Web, we have access to an ever increasing number of services from different sites that can be stitched together into ‘mash-up’ applications that leverage the best features of each site. As these mash-up applications take advantage these sites features they increasingly need authorization from the users of these site to make calls on their behalf. If I have an account with a photo printing site and I want to enable an integration with my photo sharing site, I would need to share my photo sharing user name and password with the printing site to ensure it could get access to my photos.
But isn’t the first rule of computer security to not give out your password? I’ve encountered numerous sites that want me to give out my e-mail and password so that they can check to see if any of my friends are also using the service, or to easily invite my friends to use it. Isn’t this what many e-mail viruses do; get attached to your e-mail client so they can send spam to all of your contacts? How long would a financial planning site last if it asked you for your bank password so it could check your accounts for you?
The web is all about trust and risk; I trust my mobile Twitter app with my password because the risk to me is acceptable if someone breaks into my Twitter account. I wouldn’t trust some unknown application with my bank account information. In StreamWork you don’t necessarily have information as important as bank statements, but you may be storing critical information with regard to making important business decisions, and the data and artifacts that enable those decisions. For this reason we decided to move to OAuth for authentication and authorization of third-party applications.
OAuth provides StreamWork a way to authorize applications with permission to make API calls on behalf of a end-users without those end-users being required to give up their StreamWork passwords. It also provides the end-users the ability to revoke access to specific applications without them having to worry about changing their passwords. It doesn’t solve every security concern that end-users might have with regard to third party applications and integrations with StreamWork, but it does make their passwords much more secure. End-users still need to trust the applications they authorize to integrate with StreamWork, in many cases that will be easy while others will be more difficult. It’s still about trust and risk. How much do you trust the application that wants to access your StreamWork account, and are you willing risk sharing your StreamWork account with them.
For a great explanation of OAuth, see http://hueniverse.com/oauth/
But with all of that said it definitely isn’t as easy to implement or understand how OAuth works in comparison to simple basic authentication (username and password). I’ve assembled a list most frequently asked questions to aid your implementation.
Question - Do you have any sample code?
Answer – Yes we have Java and .NET samples. We are currently looking for developers to donate sample code or client libraries for our OAuth implementation. We also have a set of CURL scripts for testing the web services which are application language agnostic.
Question – What version of OAuth are you using?
Answer – 12Sprints implements OAuth Core 1.0a of the specification http://oauth.net/core/1.0a which describes 3-legged OAuth.
Question – Can I use OAuth with a Desktop or Mobile client?
Answer – Yes, with clients that do not support URL callbacks like desktop or mobile devices you need to leave the call back URL blank when registering your application. In this scenario when the end user authorizes the application they will be given an access code, instead of being redirected back to their application. The user would then need to take the access code and enter it back into the application asking for access. The documentation outlines specifically how to handle this.
Question – What if my application doesn’t support URL callbacks?
Answer – See answer to previous question about mobile and desktop clients.
