What is OAuth?


OAuth is a set of industry standard protocols for authenticating users and authorizing access to web APIs. These protocols are designed to ensure that users are able to securely access these resources over the web (via https). If you’ve ever logged into an application using your Facebook or Google credentials, then you’ve used OAuth. The thing that sets OAuth apart from home-grown authentication schemes is that OAuth clients can easily delegate user authentication to a third-party (e.g., Facebook, Google, etc).

Currently there are two major versions of OAuth. The original OAuth1 specification and the newer OAuth2 specification. These two versions differ drastically in terms of their approach and implementation, although both share the goal of securely accessing resources over the web. For the duration of this documentation, we’ll be talking about OAuth2.

OAuth Roles


In order to understand OAuth2, it’s important to understand the concept of a role. OAuth2 has four roles:

  • Resource Owner
  • Client
  • Authorization Server
  • Resource Server

Resource Owner


A resource owner is a user that authorizes an application. Users are called resource owners because they “own” resources such as profile information, social media posts, etc. By authorizing an application (usually by typing in their login information), users grant access to these resources on behalf of a third-party application.

Client


The client is the third-party application that wants access to a user’s resources. For example, you may have downloaded an application that wants access to your Google calendar. Before this can happen, the client must be registered with the authorization server, and the user must authorize the application.

Authorization Server


The authorization server verifies a resource owner’s credentials. After verifying the credentials, the authorization server issues tokens back to the third-party application that can be used to access protected resources.

Resource Server


The resource server provides an API to access “resources” belonging to a user, such as profile information, social media posts, etc. Sometimes the authorization server and resource server are combined into a single API that both verifies and serves resources. However, this isn’t always the case. For example, Google has a single authorization server that issues tokens, but multiple resource servers for each their services (Gmail, Calendar, etc.).

Users


Each provider is responsible for storing and managing user credentials. There’s no standard way for users to register and subsequently manage their information, although most providers have similar functionality.

Registering the Client


Every application that wants to use OAuth must first be registered with the OAuth provider. Every OAuth provider has a different interface to do this, but all OAuth clients must provide the following pieces of information:

  • Application name
  • Application website
  • Redirect URI

The redirect URI is basically a webhook that gets called after the OAuth provider authenticates a user. Since the redirect URI must be called by the provider, the URI must be accessible over the web.

After registering the client application, the OAuth provider will issue a unique client ID and client secret. The client ID identifies the application and can be shared publicly. The secret however authenticates the application and should be kept private.

Authorization Flow


Before an application can access a resource, the application will need an access token. An access token is basically an encrypted string that tells the resource server which resources the user is allowed to access. Once an access token is obtained, the application has a limited amount of time to use it before it expires. In order to obtain an access token, the client application has to initiate an OAuth authorization flow. In OAuth parlance, each of these flows are also called “grant types”.

Authorization code

The authorization code flow is the most common way to authenticate a user and retrieve an access token. First, the client application redirects the user to an OAuth login portal. After the user enters their login and password successfully, the OAuth provider will then an authorization code at the registered redirect URI. This code can then be used to obtain an access token refresh token. This flow is most often used by server-based applications.

User credentials

The user credentials flow is used if the client application already has the user’s login and password. This grant type is often used when the client application is trusted and when the authorization code flow isn’t practical.

Client credentials

In the client credentials flow, the client application provides both the client ID and client secret in the initial request. Since the application has access to the client secret, it should only be used in trusted scenarios. Also, since there isn’t any actual user associated with the request, access tokens issued by this flow can only access resources that aren’t specific to a user.

Refresh tokens

Finally, if an application can use a refresh token to obtain an access token. Because a refresh token does not expire, it can be used obtain access tokens over and over again. This is useful in scenarios where an application may fetch a resource periodically and needs new access tokens regularly.

Resources


Once a client application has obtained an access token, it can supply the access token as a parameter to access various resources. So, for example, say we wanted to get “myresource”. You could construct a request like this:

request.get({ url: "1.2.3.4:8999/api/myresource",
              qs:  { 'access_token' : 'axb2y-...' }},
              function(req, res) { ... } );

Scopes


In addition to the various grant types, OAuth provides additional protection for users via “scopes”. A scope is a user-readable string that defines a set of actions an application is allowed to perform. For example, in order to view a user’s Facebook profile, an application may request the “read-user-profile” scope. If the application had a need to update the profile, it would also request the “write-user-profile” scope. Since a client application has to explicitly define the scope it plans on using, user’s can safely review (and possibly) deny access to the application.

Next Steps


Now that you have a passing familiarity with OAuth2, you’ll want to begin integrating it into your own application. The first step is to create your own OAuth2 provider. You can skip this step if you’d rather use an existing social media provider like Facebook or Google.

Afterwards, you’ll need to register your client application.

If you’re using OAuth to protect your own API, you’ll need to register endpoints.

Finally, you’ll need some users that are allowed to actually access your application.