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:

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.

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.

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:

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.

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.

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.

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.

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.

Note: Google requires that access
tokens issued using the implicit flow never expire, so you don't need to
record the grant time of an access token, as you would with other OAuth
2.0 flows.

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:

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: