OAuth + IOT Part 1: OAuth Primer

Image by Chris Messina,
licensed under the Creative Commons
Attribution-Share Alike 3.0 Unported license

Powerful apps make it easy to integrate with other services. Using your Facebook friends to populate your network in another app, or your Google account to log into other services lowers your barrier to entry for new apps. Most of these service providers (ex Google, Spotify, or Facebook) use OAuth 2 (which I will be referring to as OAuth) to expose a specific user's data to other applications. As a user of the internet, you use OAuth when you visit a website (or use an app) and are asked to give them permission to pull your music, events, files, or identity from another service.

The OAuth flow, while complex, has been well documented for web and mobile applications. In this post I am going to dive into how those flows work with OAuth and in the next post I'll explain ways to apply and adapt these flows for IOT devices. If you are looking for a more detailed explanation of OAuth I would recommend looking at this post before returning here.

What is OAuth?

A familiar OAuth example from the web

In the most general terms, the OAuth standard defines how a USER (you) can grant permission for a CLIENT (an app) to access your data from another SERVICE (ex. Facebook, Instagram, Google, etc). The full specification is covered by multiple documents [1] [2] [3] (there may be more) and there are different flows for specific situations. We will be focusing on flows which would be used with a server back-end (Authorization Code) or mobile application without a server back-end.

These flows embody some core principles to provide security and control for the USER.

• The USER should be able to give the CLIENT specific permissions to their data. for example, you can let an app access your public profile but prevent it from getting your friends list.
• The USER can revoke the CLIENT's access to their data.
• No-one should be able to sniff information passed between the USER and the CLIENT which can be used to impersonate either of them.
• If there are any "hard-coded secrets" they should be kept on a server, away from prying eyes. That means hard-coded secrets shouldn't be included in JS code or mobile apps.

What I am describing in this post (OAuth 2) is distinct from OAuth. OAuth 2 introduced better support for non-browser based applications and tokens which removed the need for cryptographic libraries on the client.

There are criticisms around OAuth 2 as well. These center around the CLIENT's and the SERVICE's challenges of managing secure access tokens, and some assumptions of security of the transport layer (you can only use OAuth2 with HTTPS). You can learn more about the differences between the versions in this post and in this technical breakdown. I will now go back to referring to OAuth 2 as OAuth.

Web OAuth Flow

Let's take a look at the process on the web, the numbers on the steps are associated with the diagram below. Here is the standard for this flow.

(1-2) A USER makes a request to your app (CLIENT) which requires their data from another SERVICE, the CLIENT tries to get data from the SERVICE, but is not authenticated.

(3-6) So the CLIENT asks the USER to log into the SERVICE in a browser and gives the USER a "redirect url" and an "identifier"* to pass to the SERVICE.

(7-9) If the USER enters the correct credentials, the SERVICE will hold onto the "identifier"* and pass back an authentication code to the USER's browser.

(10) The browser uses the "redirect url" to return to the CLIENT and passes back the auth code.

(11-12) The CLIENT will send the auth code and a new "identifier"* to the authentication server and get access and refresh tokens.

(13-15) The access token can be used by the CLIENT to get stuff from the SERVICE (ex. your calendar events). The access token is short lived (it lasts a few hours) so the refresh token can be used to get a new access token.

* The identifiers are generated from a "hard-coded secret" stored on the CLIENT server. You are assuming the CLIENT's secret will not be read by an attacker, otherwise someone could impersonate the CLIENT. A new identifier is generated in the 3rd and 11th steps, otherwise a malicious browser or observer could reuse the identifier to get permissions for itself!

OAuth for Server Client Diagram
made by Fuad Balashov, Distributed under the CC 4 License
editable version here

Mobile OAuth Flow

The OAuth flow for a mobile app without a back-end has one added design challenge, there is no secure place for the CLIENT to keep a hard-coded secret. The flow in the diagram may appear strikingly different, but the majority of the changes are because the web browser is now represented separately from the native app. The key change is the CLIENT now needs to generate a secret for each authentication request, this will be used to create the identifiers described in the previous section (I'd recommend reading the previous section if you skipped it).

To be comprehensive here is the flow with a mobile app, the numbers relate the the steps in the activity diagram below. And here is the standard for this flow.

(1) A USER makes a request to your app (CLIENT) which requires their data from another SERVICE, the CLIENT tries to get data from the SERVICE, but is not authenticated.
(2) The CLIENT generates a secret for this authentication request
(3-5) The CLIENT asks the USER to log into the service in a browser and gives the USER a "redirect url" and an "identifier" (generated from the secret) to pass to the SERVICE.

(7-9) If the USER enters the correct credentials, the SERVICE will hold onto the "identifier" and pass back an authentication code to the USER's browser.

(9) The browser uses the "redirect url" to return to the app and pass back the auth code.

(10-11) The CLIENT will send the auth code and a new "identifier" generated from the "secret" to the authentication server and get access and refresh tokens.

(12-13) The access token can be used by the app to get stuff from the SERVICE. The access token is short lived (it lasts a few hours) so the refresh token can be used to get a new access token.

OAuth for Native Activity Diagram
made by Fuad Balashov, Distributed under the CC 4 License
editable version here

Other Flows

The other flows for OAuth are not as widely supported by service providers, but they can still have specific uses where they are helpful. Here are the situations and differences associated with the other flows:

• Implicit: In the case the CLIENT application only runs in a browser you can use the "Implicit" flow. The CLIENT cannot get a refresh token in this case because it would have nowhere secure to persist it. Thus the USER needs to give the CLIENT access to the SERVICE every time they use it.
• Resource Owner Password Credentials: If the CLIENT already has the USER's credentials it can directly use them to access the SERVICE. This does not give the USER specific control over the CLIENT's access to the SERVICE.
• Client Credentials: The CLIENT application may have an account of its own to access the SERVICE. In this case there is no need for a USER to provide a grant. This is not normally supported for cases where a SERVICE is providing user controlled data.

If you want to learn more about these flows and see some informative diagrams, you can read about them on this site.

Tying it all Together

This piece was originally intended to give a background on OAuth and dive into the IOT applications of it. However, in the process of writing and learning about OAuth, I found it was too complex for just a couple paragraphs, and even in this form there are details I glossed over. Moreover, the principles I learned from the writing process caused me to realize how I had compromised security in some of my spikes. I would highly encourage everyone to take their time reading about OAuth before implementing it, regardless of how easy service providers like Google have made integration.

I hope you enjoyed the read, and that you join me for the next piece where I will dive into using OAuth for external (IOT) devices. If you see anything amiss or have any questions, please let me know in the comments.