To access a web service through its REST API, a client application must first be authenticated. OAuth client libraries, such as Google OAuth Java client library com.google.api.client.auth.oauth2, provide functions a client can use to be authenticated and authorized to access a Google Cloud service using the related REST API. For additional information, see:  OAuth 2.0 and the Google OAuth Client Library for Java.

Background

To understand how OAuth works, we first need to understand the following:

• OAuth 2.0. Standard specification for allowing end users to securely authorize a client to access protected server-side resources.
• OAuth 2.0 bearer token. Specification which explains how to access those protected resources using an access token granted during the cient authorization process.

OAuth 2.0

The OAuth 2.0 authorization framework enables a third-party application (client) to obtain limited access to a web service in one of the following ways:

• On behalf of a resource owner by orchestrating an approval interaction between the resource owner and the web service.

• By allowing the application to obtain access on its own behalf.

 The information in this section has been extrapolated from the OAuth 2.0 specification.

OAuth 2.0 Roles

OAuth 2.0 defines the following roles:

1. Client. An application making protected resource requests on behalf of the resource owner and with its authorization.  The term client does not imply any particular implementation characteristics (e.g. whether the application executes on a server, a desktop, or other devices).
2. Resource owner. 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.
3. Authorization server. The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.
4. Resource server. The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

The authorization server may be the same server as the resource server or a separate entity. A single authorization server may issue access tokens accepted by multiple resource servers.

OAuth 2.0 Protocol Flow

The following diagram shows the interactions between the various roles (actors) involved in the authentication and authorization process.

Fig 1  OAuth 2.0 Protocol Flow

1. The client requests authorization from the resource owner.  The authorization request can be made directly to the resource owner (as shown), or preferably indirectly via the authorization server as an intermediary.
2. The client receives an authorization grant, which is a credential representing the resource owner’s authorization, expressed using one of four grant types defined in the OAuth 2.0 specification or using an extension grant type.  The authorization grant type depends on the method used by the client to request authorization and the types supported by the authorization server.
3. The client requests an access token by authenticating with the authorization server and presenting the authorization grant.
4. The authorization server authenticates the client and validates the authorization grant, and if valid issues an access token.
5. The client requests the protected resource from the resource server and authenticates by presenting the access token.
6. The resource server validates the access token, and if valid, serves the request.

Terminology

Before moving ahead, let’s define some terms.

• Authorization Grant. An authorization grant is a credential representing the resource owner’s authorization to access its protected resources. A client uses the grant to obtain an access token. The OAuth 2.0 specification defines the following grant types:
  • Authorization code. The authorization code is obtained by using an authorization server as an intermediary between the client and the resource owner.
  • Implicit.The implicit grant is a simplified authorization code flow optimized for clients implemented in a browser using a scripting language such as JavaScript.
  • Resource owner password credentials. The resource owner password credentials (i.e. username and password) can be used directly as an authorization grant to obtain an access token.
  • Client credentials.The client credentials (or other forms of client authentication) can be used as an authorization grant when the authorization scope is limited to the protected resources under the control of the client, or to protected resources previously arranged with the authorization server.
• Access Token. Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client. The string is usually opaque to the client. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server.
• Refresh Token. Refresh tokens are credentials used to obtain access tokens. 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, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner). Issuing a refresh token is optional at the discretion of the authorization server.

More About Refresh Token

If the authorization server issues a refresh token, it is included when issuing an access token. A refresh token is a string representing the authorization granted to the client by the resource owner. The string is usually opaque to the client. The token denotes an identifier used to retrieve the authorization information. Unlike access tokens, refresh tokens are intended for use only with authorization servers and are never sent to resource servers.

Fig 2  OAuth 2.0 Protocol Flow with Refresh Token

1. The client requests an access token by authenticating with the authorization server, and presenting an authorization grant.
2. The authorization server authenticates the client and validates the authorization grant, and if valid issues an access token and a refresh token.
3. The client makes a protected resource request to the resource server by presenting the access token.
4. The resource server validates the access token, and if valid, serves the request.
5. Steps 3 and 4 repeat until the access token expires. If the client knows the access token expired, it skips to step 7, otherwise it makes another protected resource request.
6. Since the access token is invalid, the resource server returns an invalid token error.
7. The client requests a new access token by authenticating with the authorization server and presenting the refresh token. The client authentication requirements are based on the client type and on the authorization server policies.
8. The authorization server authenticates the client and validates the refresh token, and if valid issues a new access token (and optionally, a new refresh token).