What the Heck is OAuth?

Stormpath spends a lot of time building authentication services and libraries, we’re frequently asked by developers (new and experienced alike): “What the heck is OAuth?”.

There’s a lot of confusion around what OAuth actually is.

Some people consider OAuth a login flow (like when you sign into an application with Google Login), and some people think of OAuth as a “security thing”, and don’t really know much more than that.

I’m going to walk you through what OAuth is, explain how Oauth works, and hopefully leave you with a sense of how and where Oauth can benefit your application.

What Is OAuth?

To begin at a high level, OAuth is not an API or a service: it is an open standard for authorization and any developer can implement it.

OAuth is a standard that applications (and the developers who love them) can use to provide client applications with “secure delegated access”. OAuth works over HTTP and authorizes Devices, APIs, Servers and Applications with access tokens rather than credentials, which we will go over in depth below.

There are two versions of OAuth: OAuth 1.0a and OAuth2. These specifications are completely different from one another, and cannot be used together: there is no backwards compatibility between them.

Which one is more popular? Great question! Nowadays (at this time of writing), OAuth2 is no doubt the most widely used form of OAuth. So from now on, whenever I write just “OAuth”, I’m actually talking about OAuth2 — as it is most likely what you’ll be using.

Now — onto the learning!

What Does OAuth Do?

OAuth is basically a protocol that supports authorization workflows. What this means is that it gives you a way to ensure that a specific user has permissions to do something.

That’s it.

OAuth isn’t meant to do stuff like validate a user’s identity — that’s taken care of by an Authentication service. Authentication is when you validate a user’s identity (like asking for a username / password to log in), whereas authorization is when check to see what permissions an existing user already has.

Just remember that OAuth is a protocol for authorization, not SSO.

How OAuth Works

There are 4 separate modes of OAuth, which are called grant types. Each mode serves a different purpose, and is used in a different way. Depending on what type of service you are building, you might need to use one or more of these grant types to make stuff work.

Let’s go over each one separately.

The Authorization Code Grant Type

The authorization code OAuth grant type is meant to be used on web servers. You’ll want to use the authorization code grant type if you are building a web application with server-side code that is NOT public. If you want to implement an OAuth flow in a server-side web framework like Express.js, Flask, Django, Ruby on Rails, an Authorization Code is the way to go.

Here’s how it works:

• An anonymous user visits your website.
• They want to log into your site using a Third-Party Identity, stored somewhere else: Google, Facebook, your own OAuth service that you created, etc.
• They click a “Log In” button on your site and are redirected to their identify provider’s website (eg: Google, Facebook, etc.), and are prompted to accept certain permissions.
• If they accept these permissions, the identity provider will redirect the user BACK to your web application along with an authorization code.
• Your web server will then make a request to the identity provider’s API with the authorization code you were just given, and you’ll then be given an access token you can use to actually retrieve this user’s information.

Here’s how it typically looks:

How to Use Authorization Code Grant Types

You’ll basically create a login button on your login page with a link that looks something like this:

When the user clicks this button they’ll visit login.blah.com where they’ll be prompted for whatever permissions you’ve requested.

After accepting the permissions, the user will be redirected to back to your site, at whichever URL you specified in the redirect_uri parameter, along with an authorization code. Here’s how it might look:

You’ll then read in the code querystring value, and exchange that for an access token using the provider’s API:

NOTE: The client_id and client_secret stuff you see in the above examples are provided by the identity provider. When you create a Facebook or Google app, for instance, they’ll give you these values.

Once that POST request has successfully completed, you’ll then receive an access token which you can use to make real API calls to retrieve the user’s information from the identity provider.

The Implicit Grant Type

The implicit grant type is meant to be used for client-side web applications (like React.js or Angular.js) that don’t have a server-side component — or any sort of mobile application that can use a mobile web browser.

Implicit grants are ideal for client-side web applications and mobile apps because this grant type doesn’t require you to store any secret key information at all — this means you can log someone into your site / app WITHOUT knowing what your application’s client_secret is.

Here’s how it works:

• An anonymous user visits your website or opens your mobile app.
• They want to log into your site using a Third-Party Identity, stored somewhere else: Google, Facebook, your own OAuth service that you created, etc.
• They click a “Log In” button on your site / app and are redirected to their identify provider’s website (eg: Google, Facebook, etc.), and are prompted to accept certain permissions.
• If they accept these permissions, the identity provider will redirect the user BACK to your web application along with an access token.
• You can these use this access token to actually retrieve this user’s information.

Here’s how it typically looks:

How to Use the Implicit Grant Type

You’ll basically create a login button on your login page that contains a link that looks something like this:

When the user clicks this button they’ll visit login.blah.com where they’ll be prompted for whatever permissions you’ve requested.

After accepting the permissions, the user will be redirected to back to your site, at whichever URL you specified in the redirect_uri parameter, along with an access token. Here’s how it might look:

You’ll then read in the token query string value which you can use to make real API calls to retrieve the user’s information from the identity provider.

NOTE: The client_id stuff you see in the above examples are provided by the identity provider. When you create a Facebook or Google app, for instance, they’ll give you these values.

The Password Credentials Grant Type

The password credentials grant type is meant to be used for first class web applications OR mobile applications. This is ideal for official web and mobile apps for your project because you can simplify the authorization workflow by ONLY asking a user for their username and password, as opposed to redirecting them to your site, etc.

What this means is that if you have built your own OAuth service (login.yoursite.com), and then created your own OAuth client application, you could use this grant type to authenticate users for your native Android, iPhone, and web apps.

But here’s the catch: ONLY YOUR native web / mobile applications can use this method! Let’s say you are Google. It would be OK for you to use this method to authenticate users in the official Google Android and iPhone apps, but NOT OK for some other site that uses Google login to authenticate people.

The reason here is this: by using the password credentials grant type, you’ll essentially be collecting a username and password from your user directly. If you allow a third-party vendor to do this, you run the risk that they’ll store this information and use it for bad purposes (nasty!).

Here’s how it works:

• An anonymous user visits your website or opens your mobile app.
• They want to log into your site / app using their identity (stored in the OAuth service that you created).
• They input their username and password into your site / app, and you then validate this information via an API call and receive an access token.
• You can these use this access token to actually retrieve this user’s information.

Here’s how it looks:

How to Use the Password Credentials Grant Type

You’ll basically create an HTML form of some sort on your login page that accepts the user’s credentials — typically username and password.

You’ll then accept the user’s credentials, and POST them to your identity service using the following request format:

You’ll then receive an access token in the response which you can use to make real API calls to retrieve the user’s information from your OAuth service.

The Client Credentials Grant Type

The client credentials grant type is meant to be used for application code.

You’ll want to use the client credentials grant type if you are building an application that needs to perform non-user related tasks. For instance, you might want to update your application’s metadata — read in application metrics (how many users have logged into your service?) — etc.

What this means is that if you’re building an application (like a background process that doesn’t interact with a user in a web browser), this is the grant type for you!

Here’s how it works:

• Your application makes a request to the identity provider’s API service using it’s application credentials.
• It receives an access token back, which can be used to make API requests.

How to Use The Client Credentials Grant Type

You’ll fire off a single API request to the identity provider that looks something like this:

You’ll then receive an access token in the response which you can use to make real API calls to retrieve information from the identity provider’s API service.

NOTE: The client_id and client_secret stuff you see in the above examples are provided by the identity provider. When you create a Facebook or Google app, for instance, they’ll give you these values.

Is OAuth2 Secure?

Let’s talk about OAuth security real quick: “Is OAuth2 secure?”

The answer is, unquestionably, NO! OAuth2 is NOT (inherently) SECURE. Numerous, well-known security issues with the protocol that have yet to be addressed.

If you’d like to quickly get the low down on all of the OAuth2 security issues, I’d recommend this article, written by the famed security researcher Egor Homakov.

So, should you use it anyway? That’s a huge topic we have covered briefly in our post Secure Your API The Right Way. If you need to secure an API, this post will help you choose the right protocol.

Key Takeaways

Hopefully this article has provided you with some basic OAuth knowledge. I realize there’s a lot to it, but here are some key things to remember:

Know What Grant Type to Use

If you’re building an application that integrates with another provider’s login stuff (Google, Facebook, etc.) — be sure to use the correct grant type for your situation.

If you’re building….

• A server-side web app: use authorization code.
• A client-side web app (or mobile app): use implicit.
• An integration with an OAuth service you built yourself, use password credentials.
• An application that doesn’t interact with user data: use client credentials.

Don’t Use OAuth2 for Sensitive Data

If you’re building an application that holds sensitive data (like social security numbers, etc.) — consider using OAuth 1.0a instead of OAuth2 — it’s much more secure.

When to Use OAuth

You should only use OAuth if you actually need it. If you are building a service where you need to use a user’s private data that is stored on another system — use OAuth. If not — you might want to rethink your approach!

There are other forms of authentication for both websites and API services that don’t require as much complexity, and can offer similar levels of protection in certain cases.

Namely: HTTP Basic Authentication and HTTP Digest Authentication.

Use Stormpath for OAuth

Our service, Stormpath, offers the password and client credential workflows as a service that you can add to your application quickly, easily, and securely. Read how to:

• Use Stormpath for API Authentication
• Build an API Service With Oauth2 Authentication
• Use Stormpath for Social Login with Facebook, Google and more

If you’ve got any questions, we can be reached easily by email.

And… That’s all! I hope you enjoyed yourself =)