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.
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:
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
Find your project ID on the Settings page of the Google API Console.
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:
The sign-in request includes the following parameters:
|Authorization endpoint parameters|
||The client ID you assigned to Google.|
||The URL to which to send the response to this request.|
||A bookkeeping value that is passed back to Google unchanged in the redirect URI.|
||The type of value to return in the response. For the OAuth 2.0 implicit
flow, the response type is always
Your authorization endpoint handles the sign-in request by doing the following:
- Confirm that the
client_idmatches the client ID you assigned to Google.
- Confirm that the URL specified by the
redirect_uriparameter has the following form:
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_IDYOUR_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
- Confirm that the
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
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.
Send an HTTP response that redirects the user's browser to the URL specified by the
redirect_uriparameter. Include all of the following parameters in the URL fragment:
access_token: the access token you just generated
token_type: the string
state: the unmodified state value from the original request
For example, redirect the user to URL like the following:
Google's OAuth 2.0 redirect handler will receive the access token and confirm
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:
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.
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.
If you have revoked an access token, return a 401 error to any request that uses that token to indicate to Google that a new access token must be acquired.
Validate your implementation
You can validate your implementation by using the OAuth 2.0 Playground tool. In the tool, do the following steps:
- Click the gear icon to open the OAuth 2.0 Configuration window.
- In the OAuth flow field, select Client-side.
- In the OAuth Endpoints field, select Custom.
- Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
- 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.
- In the Step 2 and Step 3 sections, step through the OAuth 2.0 flow and verify that each step works as intended.