An Introduction to OAuth and How CloudRail Simplifies it
One of the most intricate aspects of API integration can be authentication when OAuth 1.0 or OAuth 2.0 are used, especially for developers that are not familiar with it. Both authentication schemes share the same purpose, allowing an application to interact with a third party service on behalf of a user without the user having to reveal their credentials to the application.
For example, an Android application might want to post to a user’s Facebook wall. Instead of asking the user for their credentials and then logging in to Facebook, the application will redirect the user to a special Facebook page. On this page, the user logs in to their Facebook account (this means the application does not see the credentials) and then grants access to the application. The application will be notified by Facebook and receive a token which it can then use to interact with the Facebook API and post to the user’s wall on their behalf.
OAuth 2.0 is a non-backwards compatible, revamped version of OAuth 1.0. It supports different flows that better fit non-browser based applications. Moreover, it does not require explicit cryptography as it mandates the use of HTTP with SSL/TLS a.k.a. HTTPS which also makes it easier to implement. Besides, it allows short lived tokens that must be refreshed for improved security.
OAuth is the de-facto standard for secure delegated access. OAuth 2.0 is used by the large majority of services but OAuth 1.0 still has prominent advocates with e.g. Twitter’s API. OAuth 2.0 is needed to access the APIs of Facebook, Google, Microsoft and Dropbox to only name a few. Thus, if you need integrations to social networks or cloud storages there is virtually no way around OAuth.
How CloudRail Simplifies the OAuth Process
Users of the CloudRail API integration solution do not require deep insights into this process, especially when they are using the SDKs for mobile platforms (Android, iOS). On mobile, the CloudRail SDKs use WebViews or the device’s browser to automatically complete the authentication process. However, when using any of the backend-oriented SDKs (e.g. Java, NodeJS) the developer needs to be involved into one particular part of the OAuth process. This is due to the many different environments and frameworks that exist on Desktop and Server platforms which requires this part to stay parametric and thus highly flexible.
The module that the developer needs to provide is referred to as a RedirectReceiver in our documentation and SDKs.
If you have had a closer look at CloudRail before, you may have already encountered it.
We will outline how the OAuth schemes and flows work without getting into too much detail. We then focus on the aforementioned part of the OAuth process that developers using non-mobile CloudRail SDKs should be aware of (RedirectReceiver).
How OAuth works
We focus on the so called “three legged” flows since these are most commonly used by popular services and also the ones the CloudRail SDKs implement. The two graphics illustrate on a high level how they work for OAuth 1.0 and 2.0 respectively.
It should be noted that both flows require the application to present a website to the user on which the user grants authorization to the application.
This is precisely the part that CloudRail keeps parametric with its RedirectReceiver.
A desktop application might use the local browser to present this website to the user and listen on a port on localhost to receive the redirect. It could also use a module of a framework to present the website inline and listen to website redirects (e.g. Node’s Electron or Java’s JavaFX). A server application might redirect the user’s browser to the website and receive redirects on a server endpoint. Even more scenarios are possible which is why the developer needs to take this step into their own hands by providing a RedirectReceiver. All the other steps are handled by the CloudRail SDKs. This includes the generation of the URL to the website the user should be presented with (which involves an API request for OAuth 1.0), the exchange of the code from the redirect for an access token and necessary refreshes of the access token with the refresh token.
All non-mobile CloudRail SDKs come with a selection of RedirectReceiver implementations for the most common use cases. E.g., there are implementations with a local server for testing on both NodeJS and Java (also the default in our code examples) and implementations for the NodeJS framework Electron and Java’s JavaFX.
The RedirectReceiver is/has a function that the CloudRail SDKs call whenever they perform OAuth authentication and only continue their execution when the RedirectReceiver function returns. The function receives a URL which should be displayed to the user and must return the incoming redirect.
We will have a look at an example for a web server that runs on “https://example.com”. We use pseudocode to keep it brief and platform-independent, platform-specific examples can be found in the documentation and on GitHub.
The server sketched in above pseudo-code has two endpoints. One serves to trigger the authentication process by a browser client. The other is for the Facebook server to redirect the browser client to once the user has granted access to your application on the Facebook consent page.
The first endpoint initializes an instance of the Facebook integration provided by the CloudRail SDK, passing in application credentials and the URL that the Facebook server should redirect to. The RedirectReceiver takes the url parameter and redirects the user’s browser to it. The whole process is triggered by a call to the login method but in fact any method that needs prior authentication would do as well. The method will never finish as the RedirectReceiver interrupts it (depending on the platform this can be returning null which will trigger an exception that can be swallowed and ignored or not calling a callback. Please refer to the platform specific documentation and examples).
The second endpoint will then receive an incoming request once the user has granted access which contains credentials that the CloudRail SDK can process and finish authentication with. This is why the RedirectReceiver here just returns the incoming URL to the CloudRail SDK. Again, the running of the CloudRail SDK is triggered by a method which this time will run through successfully. Presto, you have an instance of Facebook that can make any requests against the Facebook API authenticated as the user that logged in on the Facebook consent page.
The last parameter to the Facebook instances which we just set to a constant string can be used for different purposes. It will appear as the “state” key in the query of the incoming request to “/finish-facebook-authentication”. It could be leveraged to identify different users or to transmit a token to defend against CSRF (generate a secret value in startFacebookAuthentication and verify its correctness in finishFacebookAuthentication) but we omit this here for simplicity.
We have learned about the OAuth authentication scheme and how we can use CloudRail to significantly simplify this process. We have seen an example to better understand the part where the developer needs to get involved. If you use one of the non-mobile SDKs and there is no predefined RedirectReceiver for your use case this should help you implement your own.
In case you are having trouble, shoot an email to firstname.lastname@example.org.