Implementing OAuth2 flow in RESTful APIs/Services using Google Authorization Server

A RESTful API positions a given service to present business value, and protection of the data provided via RESTful endpoints should always be a high priority. Aside from use of TLS/HTTPS, the most important level of RESTful API security is centered around authentication. For this article, the focus is going to be on OAuth2, which can perform pseudo-authentication through delegation.

OAuth is a standard for delegating authorization of resources and is a common mechanism used by many API developers/providers to accomplish user authentication. However, OAuth is not an authentication protocol; the core functionality of OAuth is about user identity-delegation for consent to access the protected resource / data / business logic. The 'delegated access' means user is not present on the connection between the client and the resource being accessed. OAuth.net is a great reference to learn more about the topic.

This page describes how to implement OAuth 2.0 basic flow within a Dropwizard RESTful application with Google as the Authorization Server.

At a high level, you follow four steps:

1. Obtain OAuth 2.0 credentials from the Google API Console.
2. Register the client application user with Google, sign the user in and obtain an access token.
3. The REST client includes the access token it receives from Google in every request it sends to the Dropwizard application.
4. The Dropwizard OAuth authentication implementation validates the access token and if valid, serves the request to protected resources.

The following sequence diagram captures the OAuth2 flow interaction between the REST Client, RESTful application (Resource Server) and the OAuth2 Server (Google Authorization Servers). 

In this sample OAuth implementation, the authorization server is Google and is separate from the resource server which is a Dropwizard application. 

1. Obtain OAuth 2.0 Credentials

An OAuth Client-ID is needed to use OAuth 2.0 in your application.

To begin, obtain OAuth 2.0 credentials such as a client ID that is known to both Google and your application from the Google API console. Select the appropriate application type for your project. Follow the instructions in Setting up Google OAuth 2.0 to create the OAuth client ID. The Client-ID will be used by the application when requesting an OAuth 2.0 access token.

2. Register the Client application User and obtain Access Token

Using the Client-ID from step-1, simulate a client-side OAuth 2.0 flow.

a) First, get the Authorization-Code.
Simply, add your OAuth client-ID credential to a URI and get the authorization-code by sending the HTTPS request through your web browser. This authorization flow supplies a local redirect URI to handle responses from Google's authorization server.

For example, send the URI request to Google's OAuth 2.0 server:
      https://accounts.google.com/o/oauth2/v2/auth?
                             scope=profile&
                             response_type=code&
                             redirect_uri=urn:ietf:wg:oauth:2.0:oob&
                             client_id=<<ENTER-CLIENT-ID>>

This Google OAuth2.0 endpoint handles active session lookup, authenticates the user, and obtains user consent. Login to your google account to COPY/PASTE the output i.e Authorization-Code.

b) Next, obtain the Access Token using authorization-code
Use the authorization-code to get the access token (in JSON format). The manner in which your application receives the authorization response depends on the redirect-URI scheme that it uses.

Exchange authorization code for refresh and access tokens. Call the https://www.googleapis.com/oauth2/v4/token endpoint and set the authorization_code, client-id and client_secret parameters. For example, where credential Application type is "Other", you can click the Download JSON button to get the client_secret.json file.
      https://www.googleapis.com/oauth2/v4/token?
                  code=<enter-authorization_code>&
                  client_id=<enter-client_id>&
                  client_secret=<enter-client_secret>&
                  redirect_uri=urn:ietf:wg:oauth:2.0:oob&
                  grant_type=authorization_code
 
Google responds to this request by returning a JSON object that contains a short-lived access token and a refresh token.

Follow the Google instructions (steps 2-5) in Obtaining OAuth 2.0 access tokens for more details.

3. Include the Access Token in every request to fetch protected REST Resource:-

After your application obtains an access token, you can use the token to make calls to the REST endpoints. The client application  must include the access token it receives from Google in every request it sends to the resource server, which in this example is a Dropwizard application.

For example, to invoke the API via the curl command-line, include the access token in a request to the API by including either an access_token query parameter or an Authorization: Bearer HTTP header.

     curl -H "Authorization: Bearer <access_token>" https://<my-apis-domain>/<rest-endpoint>

4. Validate OAuth2 Access Token:-

Finally, it is important for the REST/Dropwizard application to implement a mechanism for validating access token, as it has no way of differentiating between a valid token and an attack token. This can be mitigated by using the authorization code flow and only accepting tokens directly from the authorization server's token endpoint.

To setup OAuth 2.0 authentication within Dropwizard, it is best to follow instructions on Dropwizard Authentication tutorial. The necessary thing to understand is that an AuthFilter needs to be created and registered with a jersey provider. The AuthFilter then will be applied to every request sent to the server before the request is dispatched to a resource method. The filter extracts the access token from a request and asks the Authenticator (i.e. GoogleAuthenticator in this example) to authenticate the user and return a principal object.

Here is a sample code (for demonstration only, not to be used in production) for Dropwizard-Auth2 Google-Authenticator
   
The Dropwizard OAuth2 implementation validates the access token and if valid, serves the request to protected resources.