Open Authorization Standard (OAuth)

OAuth (Open Authorization) is an open standard for implementing token-based authorizations. OAuth 2.0 refers to the second version of the “Open Authorization” standard, published in 2010, and described in RFC 6749. OAuth 2.0 is used to grant access to Web resources without the need to provide usernames and passwords over the Internet. OAuth may be used with desktop, Web and mobile applications.

OAuth Terminology

There are a number of documents describing OAuth available on-line. Regretfully, there is a lack of consistency in the descriptions and terminology used in many of these documents. This document provides an overview of OAuth security that is stated simply and attempts to use industry standard terms to describe components of the OAuth security model.

We begin the discussion of OAuth security with some basic terminology. Note that the terms “application”, “client” and “user” have special meaning in OAuth terminology:

• Application: aka “the Client”; is an entity that makes authorized resource requests on behalf of the resource owner;
• Authorization Server: responsible for issuing OAuth access tokens after the client authenticates
• Resource Owner: aka “the User”; an entity capable of granting access to a protected resource; when the resource owner is a person, it is referred to as an end-user;
• Resource Server: hosts the API; grants access to the API when a valid access token is presented.

OAuth Authorization Flow (Abstract)

Figure 1 depicts an OAuth abstract authorization flow. Every application that sends requests to a web service is playing the role of a “client”. When making a request to a Web service that is protected by OAuth, the application must obtain an access token and forward the token as part of the API request.

Figure 1 - OAuth Authorization Flow (Generic)

In the next section of this document, OAuth Grant Types are discussed. Grant Types can be thought of as authorization flows that have been tailored and optimized for specific use cases.

OAuth Tokens

Tokens are issued to an application (client) by an authorization server with the approval of the resource owner. There are two major categories of tokens used in OAuth - access tokens and refresh tokens. Access tokens are used to make API requests on behalf of a user. Refresh tokens are used to obtain a new access token when the current access token becomes invalid or expires. The application (client) uses the access token to gain access the protected resources (e.g. user data) hosted by the resource server.

Bearer Tokens

Bearer Tokens are the predominant type of access token used with OAuth 2.0. A Bearer Token is an opaque string (like a GUID) that does not convey any specific meaning as described in RFC 3749. Some authorization servers will issue bearer tokens that are a short string of hexadecimal characters. Others may use structured tokens such as JSON Web Tokens.

Application Registration

In order to acquire an access token, the application (client) must first be registered. When the developer registers the application, the Client ID and the client secret is generated. The OAuth standard does not specify the registration process, only the information that is required for registering the application (client).

OAuth Credentials and Secrets

The Client ID (client_id) is the public identifier for the application. Client ID’s must be unique for each authorization server and are often generated as 32-character hex strings. The Client Secret (client_secret) should be known only to the application (client) and the authorization server. Client Secret’s are best generated using a cryptographically secure library (e.g. Python’s secrets module). Client Secrets are note used for mobile or SPA Web applications as the secret would need to be stored in plaintext within the app.

OAuth Grant Types

In OAuth 2.0, the term “grant type” (aka “flow”) is used to reference the manner in which an application acquires an access token. Each grant type is optimized for a particular use case, whether a web application, a native application, a device without the ability to launch a web browser, or an application that implements server-to-server communications.

Client Credential Grant

This grant type is used for machine-to-machine authentication. The access token is issued to the application rather than to an end-user. This authorization flow includes the following steps:

1. The application (client) authenticates with the authorization server and requests an access token
2. The authorization server authenticates the application, and if valid, issues an access token

Authorization Code Grant

This grant type is used by Web applications running on a server. The authorization code grant is used when an application exchanges an authorization code for an access token. After the user returns to the application via the redirect URL, the application will get the authorization code from the URL and use it to request an access token. This authorization flow includes the following steps:

1. The application opens a browser to send the user to the authorization end-point
2. The user receives an authorization prompt and approves the application’s request
3. The user is redirected back to the application with an authorization code
4. The application exchanges the authorization code for an access token

Resource Owner Password Grant

This grant type Is used where the resource owner has a trust relationship with the application (client). The application launches a traditional username and password login form to collect the user’s credentials. The application then makes a POST request to the authorization server to exchange the password for an OAuth access token. In this scenario, the application only has to acquire the user’s password for as long as it takes to get the access token, then it can store and use the access token instead of the password.

Implicit Grant

The Implicit grant type is a simplified flow that can be used by mobile and JavaScript applications. The access token is returned immediately without an extra authorization code exchange step. The implicit grant type has been used by clients that aren’t able to securely store a client secret. SPA (Single Page Architecture) and mobile applications are examples of applications that are not able to securely store client credentials.

Refresh Token Grant

Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires. A refresh token is a string representing the authorization granted to the client by the resource owner. Unlike access tokens, refresh tokens are intended for use only with authorization servers. Refresh tokens are never sent to resource servers.

Issuing a refresh token is optional. Typically, refresh tokens are only used with confidential clients. If the refresh token was issued to a confidential client, the service must ensure the refresh token in the request was issued to the authenticated client. Refresh tokens can not be used with the Implicit Grant type.

Selecting the OAuth Grant Type

Figure 2 depicts a flow chart that can be used to match an application to the appropriate grant type. As indicated previously, use of the Implicit Grant Type is no longer recommended.

Figure 2 - Determining the OAuth Grant Type

Other OAuth Resources

• OAuth 2.0 Simplified
• OAuth 2.0 Specification