Google Accounts Authentication and Authorization

Using OAuth 2.0 for Devices

If you are developing for Android or iOS, use Google+ Sign-In.

This document is for you if:

  • You are writing an installed app for a platform other than Android or iOS, and
  • Your app will run on devices that do not have access to a system browser, or devices with limited input capabilities; for example if your app will run on game consoles, video cameras, or printers.

If you are writing an app for Android or iOS, use Google+ Sign-In to authenticate your users. The Google+ Sign-In button manages the OAuth 2.0 flow both for authentication and for obtaining authorization to Google APIs. Google+ Sign-In works for all users with a Google account, whether or not they have upgraded to Google+. To add the Google+ Sign-In button, follow the steps for Android or iOS.

If you are writing an installed app that is not for Android or iOS, and if the app will run on devices that have a system browser and rich input capabilities such as a full keyboard, then see Using OAuth 2.0 for Installed Applications.

Contents

  1. Overview
  2. Obtaining a user code
  3. Obtaining access tokens and refresh tokens
  4. Calling a Google API
  5. Using a refresh token

Overview

Applications that run on devices with limited input capabilities (such as game consoles, video cameras, and printers) can access a Google API on behalf of a user, but the user must have separate access to a computer or device with richer input capabilities. The flow is as follows:

  • Your application begins this flow with a request to a Google URL with a set of parameters. The response includes a device code, a user code, a URL, an expiration, and a suggested polling interval.
  • After receipt of this response, your application shows the user the URL and the user code, and instructs the user to open a browser, navigate to the URL, and enter the code.
  • The user switches to a device or computer with richer input capabilities, launches a browser, navigates to the URL specified on the limited-input device, logs in, and enters the code.
  • In the background, your application polls a Google endpoint for an access token and a refresh token. These tokens will only be returned to your application after the user has logged in and approved the request.
The user logs in on a separate device that has a browser.

Given the variety in capabilities and runtime environments of these devices, the examples shown in this document use the curl command line utility. It should be a trivial exercise to port the curl commands to various languages and runtimes.

Obtaining a user code

As in all OAuth 2.0 scenarios, you first need to set up a project in the Google Developers Console and obtain a client ID and client secret.

After you have the client ID and client secret, you send an HTTP POST to the OAuth 2.0 device endpoint at https://accounts.google.com/o/oauth2/device/code with your client_id and a list of scopes. Unlike the other OAuth 2.0 flows, response_type and redirect_uri are not needed in the device flow. The following is an example request for a user code:

POST /o/oauth2/device/code HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=812741506391-h38jh0j4fv0ce1krdkiq0hfvt6n5amrf.apps.googleusercontent.com&
scope=email%20profile

or using curl:

curl -d "client_id=812741506391-h38jh0j4fv0ce1krdkiq0hfvt6n5amrf.apps.googleusercontent.com&
scope=email profile"
https://accounts.google.com/o/oauth2/device/code

The response is returned in a JSON object:

{
  "device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y",
  "user_code" : "a9xfwk9c",
  "verification_url" : "http://www.google.com/device",
  "expires_in" : 1800,
  "interval" : 5
}

The user_code and verification_url from the JSON object should be shown to your user. The idea is to ask the user to go to a browser, navigate to the verification_url URL, and enter the user_code. The user_code is case sensitive, so the user will need to enter the code exactly as it appears in the response. The device_code, expires_in, and interval fields will be used in the next section.

When the user navigates to that URL, they will see a page similar to the following:

After the user enters the user_code, they will be asked to login to Google, and will see a consent screen (shown below).

If the user clicks "Allow Access", then your application can obtain an access and refresh token that will grant your application access to one or more Google APIs. As in all OAuth 2.0 scenarios, the scope parameter controls the access your application has to a Google API.

Obtaining access tokens and refresh tokens

After your application has shown the user the user_code and the verification_url, your application may begin polling a Google endpoint with the device_code that was returned with the user_code and verification_url. The URL of the endpoint to poll is https://accounts.google.com/o/oauth2/token, and the interval between requests is specified as the interval in seconds. Such a request is shown below:

POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=812741506391-h38jh0j4fv0ce1krdkiq0hfvt6n5amrf.apps.googleusercontent.com&
client_secret={clientSecret}&
code=4/L9fTtLrhY96442SEuf1Rl3KLFg3y&
grant_type=http://oauth.net/grant_type/device/1.0

or using curl:

curl -d "client_id=812741506391-h38jh0j4fv0ce1krdkiq0hfvt6n5amrf.apps.googleusercontent.com&
client_secret={clientSecret}&
code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss&
grant_type=http://oauth.net/grant_type/device/1.0"
https://accounts.google.com/o/oauth2/token

If the user has not yet approved the request, the response will appear as follows:

{
  "error" : "authorization_pending"
}

Your application should repeat these requests at the rate that does not exceed the value of interval field. If your application polls too quickly, then the response will appear as follows:

{
  "error" : "slow_down"
}

Once the user logs in and grants your application access to a Google API, the next polling request will result in an access and refresh token (shown below).

{
  "access_token" : "ya29.AHES6ZSuY8f6WFLswSv0HELP2J4cCvFSj-8GiZM0Pr6cgXU",
  "token_type" : "Bearer",
  "expires_in" : 3600,
  "refresh_token" : "1/551G1yXUqgkDGnkfFk6ZbjMLMDIMxo3JFc8lY8CAR-Q"
}

Upon receipt of this response, your application may use the access token in Google API requests. Access tokens have a limited lifetime. If your application needs access to an API over a long period of time, then it can use the refresh token to obtain a new access token (see Using a refresh token). If your application needs this type of access, then it should store the refresh token for later use.

Calling a Google API

After your application obtains an access token, you can use the token to make calls to a Google API on behalf of a given user. To do this, include the access token in a request to the API by including either an access_token query parameter or an Authorization: Bearer HTTP header. When possible, it is preferable to use the HTTP Header, since query strings tend to be visible in server logs. In most cases you can use a client library to set up your calls to Google APIs (for example, when calling the People API).

You can try out all the Google APIs and view their scopes at the OAuth 2.0 Playground.

Examples

A call to the people.get endpoint (the People API) using the access_token query string parameter might look like the following:

GET https://www.googleapis.com/plus/v1/people/{userId}?access_token=1/fFBGRNJru1FQd44AzqT3Zg

Here is a call to the same API for the authenticated user (me) using the access_token Authorization: Bearer HTTP header:

GET /plus/v1/people/me HTTP/1.1
Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg
Host: googleapis.com

You can try either out in the CURL command line application. Here's an example of the query string parameter option:

curl https://www.googleapis.com/plus/v1/people/me?access_token=1/fFBGRNJru1FQd44AzqT3Zg

And the HTTP header option:

curl -H "Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg" https://www.googleapis.com/plus/v1/people/me

Using a refresh token

Access tokens expire. An API will indicate that an access token has expired when it returns a 401 status code. To obtain a new access token, make a request to the token endpoint and include the client_id, client_secret, refresh_token, and grant_type parameters (shown below).

POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=812741506391-h38jh0j4fv0ce1krdkiq0hfvt6n5amrf.apps.googleusercontent.com&
client_secret={clientSecret}&
refresh_token=1/551G1yXUqgkDGnkfFk6ZbjMLMDIMxo3JFc8lY8CAR-Q&
grant_type=refresh_token

Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.