Integrate with Google Using the OAuth 2.0 Implicit Flow

This document explains how to implement a minimal OAuth 2.0 server that supports the implicit flow, sufficient for integrating your service with Google. The implicit flow is simple to implement, but has some tradeoffs when compared to other supported OAuth 2.0 flows.

Overview

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authenticating and obtaining consent from users for data access. The authorization endpoint presents sign-in UI to your users that aren't already signed in and records consent to the requested access.

When Google needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf. A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

  1. First, Google opens your authorization endpoint in the user's browser. The user signs in if not signed in already, and grants Google permission to access their data with your API if they haven't already granted permission.
  2. Then, your service creates an access token and returns it to Google by redirecting the user's browser back to Google with the access token attached to the request.
  3. Lastly, Google calls your service's APIs, attaching the access token with each request. Your service verifies that the access token grants Google authorization to access the API, then completes the API call.

Before you begin

Before you add OAuth 2.0 authorization to your service, do the following:

  1. Decide what the URL of your authorization endpoint will be. For example: https://myservice.example.com/auth

    The authorization endpoint must be accessible only over HTTPS; it must not accept unencrypted HTTP requests.

    Oftentimes an existing sign-in page can be adapted to serve this purpose.

  2. Assign Google a client ID of your choosing, which Google passes to your authorization endpoint indicating that it originated the request. The client ID can be any URL-safe string; for example, it could simply be google.

  3. Find your project ID on the Settings page of the Google API Console.

  4. Register the information above by following the steps in Enabling Account Linking.

Handle authorization requests

When Google needs to access your service's resources, Google sends the user to your authorization endpoint with a URL of the following form:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

The sign-in request includes the following parameters:

Authorization endpoint parameters
client_id The client ID you assigned to Google.
redirect_uri The URL to which to send the response to this request.
state A bookkeeping value that is passed back to Google unchanged in the result.
response_type The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.

Your authorization endpoint handles the sign-in request by doing the following:

  1. Verify the client_id and redirect_uri values:

    • Confirm that the client_id matches the client ID you assigned to Google.
    • Confirm that the URL specified by the redirect_uri parameter has the following form:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      YOUR_PROJECT_ID is the ID found on the Settings page of the Google API Console, which you registered with Google.

    These checks are important to prevent granting access to unintended or misconfigured client apps.

    If you support multiple OAuth 2.0 flows, also confirm that the response_type is token.

  2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

  3. Generate an access token that Google will use to access your API. The access token can be any string value but it must uniquely represent the user and the client the token is for, and not be guessable.

    A common way to implement access tokens is to create a database record for each token granted, indexed by a cryptographically secure number, generated with 128 bits (16 bytes) of entropy, and to use the base64-encoded index number as the access token. For example, you might have an Authorizations table like the following:

    AccessToken UserID ClientID
    YWJjZGVmZ2hpamtsbW5vcA== 1234 google

    Another way to implement access tokens is to create a JSON object containing the user ID and the client ID you assigned to Google. Then, encrypt the JSON object with a symmetric encryption algorithm such as AES and use the resulting string as the access token.

  4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

    • access_token: the access token you just generated
    • token_type: the string bearer
    • state: the unmodified state value from the original request

    For example, redirect the user to URL like the following:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler will receive the access token and confirm that the state value hasn't changed. After Google has obtained an access token for your service, Google will attach the token to subsequent calls to your service's APIs.

Handle data access requests

Your service's API endpoints use the access token to identify the user on whose behalf Google is making the API call, and to verify that Google has authorization to access the endpoint on the user's behalf.

A common way for services to attach access tokens to requests is by using the Authorization header. For example, Google might make the following request to your service:

GET /mycontent HTTP/1.1
Host: myservice.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer ACCESS_TOKEN

The specific method of attaching an access token to a request depends on the Google service that's calling your API. See the service's developer documentation for details.

Regardless of how the access token is sent, your endpoint does the following:

  1. If you implemented the access token as an index in a database, verify the index exists and then retrieve the authorization record.

    If you implemented the access token as an encrypted object, use the encryption method you chose to decode the access token.

  2. Use the user ID from the access token to respond to the request.

Your OAuth 2.0 implementation is now sufficient for integration with Google services.

Validate your implementation

You can validate your implementation by using the OAuth 2.0 Playground tool. In the tool, do the following steps:

  1. Click the gear icon to open the OAuth 2.0 Configuration window.
  2. In the OAuth flow field, select Client-side.
  3. In the OAuth Endpoints field, select Custom.
  4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
  5. In the Step 1 section, don't select any Google scopes; instead, type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes), and click Authorize APIs.
  6. In the Step 2 and Step 3 sections, step through the OAuth 2.0 flow and verify that each step works as intended.