OAuth 1.0 API Reference

Important: OAuth 1.0 was officially deprecated on April 20, 2012, and is no longer supported. We encourage you to migrate to OAuth 2.0 as soon as possible.

The first section in this document describes how to migrate your code from OAuth 1.0 to OAuth 2.0. The rest of the document describes Google's implementation of the deprecated OAuth 1.0 open standard for authorization, and explains how to implement OAuth 1.0 in an application.

Migrating from OAuth 1.0 to OAuth 2.0

This section describes how to migrate your application from OAuth 1.0 to OAuth 2.0, without end-user intervention. After migration, your application can stop using the OAuth 1.0 library and can access resources using OAuth 2.0 tokens.

If you are unsure whether you are using OAuth 1.0, complete the following steps:

  1. Revoke the access token associated with your application for your user account:
    1. Go to Google's Account Permissions page.
    2. Select your application from the list.
    3. Click Revoke access.
  2. Access your application.
    • If the consent screen includes a deprecation notice, you must migrate to OAuth 2.0.
    • If the URL of the consent screen includes the string /oauth1, you must migrate to OAuth 2.0.

Prerequisites for this migration:

  • Your application must have a valid OAuth 1.0 access token (which implies that your application has a valid grant).
  • Your application must have an OAuth 2.0 client ID and client secret. You get these OAuth 2.0 credentials by registering the application as a web app or a native app in the Google API Console.

To find your OAuth 2.0 credentials in the Google API Console:

  1. Open the Credentials page in the API Console.

You present both the OAuth 1.0 and OAuth 2.0 credentials in a single request; there is no other binding of the two grants. The idea is to exchange an OAuth 1.0 grant for an OAuth 2.0 refresh token. The basic flow is shown in the following figure.

The flow is as follows:

  1. The process is triggered when an OAuth 1.0 consumer (your application) sends a migration request to Google’s OAuth 2.0 token endpoint.
  2. The credentials in the migration request are validated.
  3. An OAuth 2.0 refresh token is issued to your application in the response to your migration request.
  4. Your application uses OAuth 2.0 flows to exchange the refresh token for an OAuth 2.0 access token. (Note that when the refresh token is used, the OAuth 1.0 access token will expire in 1 hour.)

As soon as your application obtains the OAuth 2.0 access token, it can drop the OAuth 1.0 token and use OAuth 2.0 tokens to access users' resources.

Sending a migration request

You send a grant migration request to the existing Google OAuth 2.0 token endpoint, which is https://oauth2.googleapis.com/token. The request must be a POST, and you must send it via HTTPS. The endpoint refuses HTTP requests.

Signed-request flow for migration

Request

The request is a signed OAuth 1.0 request with additional OAuth 2.0 request parameters. You include the OAuth 1.0 consumer key, token secret, and signature in the OAuth 1.0 authorization HTTP header. For example:

Authorization: OAuth realm="example",
               oauth_consumer_key="9djdj82h48djs9d2",
               oauth_token="kkk9d7dh3k39sjv7",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="137131201",
               oauth_nonce="7d8f3e4a",
               oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"

All the fields are required except realm. Applications can use any OAuth 1.0 library to generate the header.

There are three required OAuth 2.0 request parameters (grant_type, client_id, and client_secret) and an optional parameter (scope):

  • grant_type=urn:ietf:params:oauth:grant-type:migration:oauth1

    Required. This is a fixed value.

  • client_id

    Required. This is the OAuth 2.0 client ID, which you get from the Google API Console.

  • client_secret

    Required. This is the OAuth 2.0 client secret, which you get from the Google API Console.

  • scope

    Optional. Use the scope parameter when you want to "down-scope" and request fewer OAuth 2.0 scopes than were granted via OAuth 1.0. List the requested scopes in the scope parameter, separated by spaces. Any other scopes are dropped, and the requested scopes are validated. If you do not provide the scope parameter, the requested scopes are those previously granted via OAuth 1.0.

An example request follows — be sure to replace YOUR_CLIENT_SECRET with your value of client_secret.

POST /oauth2/v3/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 88
Authorization: OAuth realm="example",
               oauth_consumer_key="9djdj82h48djs9d2",
               oauth_token="kkk9d7dh3k39sjv7",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="137131201",
               oauth_nonce="7d8f3e4a",
               oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Amigration%3Aoauth1&
client_id=8819981768.apps.googleusercontent.com&
client_secret=YOUR_CLIENT_SECRET

A note on the signature: Make sure to follow the OAuth1 signature specification when signing your migration request.

Response

After a migration request is validated, your application is issued a refresh token with down-scoped scopes. The response body is in JSON format, and it contains only an OAuth 2.0 refresh token (no access token).

An example response is shown below:

{
  "refresh_token" : "1/IJ8bRmYIH4t6iE761H3XW9JwqzsGFCA8wnQ7gck_3NU"
}

Obtaining an OAuth 2.0 access token

Exchange the refresh token for an OAuth 2.0 access token, as described in Refreshing an access token.

About refresh tokens:

  • Refresh tokens never expire unless revoked.
  • It is the responsibility of your client software to store the refresh token permanently and securely.

Unsigned-request flow for migration

If you have a native application and do not want to sign the request, you can use a no-signature flow. In this flow, your application sends all the necessary credentials in the request parameters over SSL. No authorization header is needed in this case. This also allows native applications to drop OAuth 1.0 libraries, either immediately or in a future version, and still have an upgrade path.

Request

In an unsigned-request flow, include the following OAuth 2.0 parameters in your request:

  • grant_type=urn:ietf:params:oauth:grant-type:migration:oauth1
  • client_id
  • client_secret
  • scope

The rules governing the parameters, and their meanings, are identical to those in the signed-request flow.

Also include the following OAuth 1.0 parameters:

  • oauth_consumer_key
  • oauth_consumer_secret
  • oauth_token
  • oauth_token_secret

An example request follows — be sure to replace YOUR_TOKEN_SECRET and YOUR_CLIENT_SECRET with your values of oauth_token_secret and client_secret

POST /oauth2/v3/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 473

oauth_consumer_secret=anonymous&
oauth_consumer_key=anonymous&
oauth_token=YOUR_TOKEN_SECRET&
client_id=8819981768.apps.googleusercontent.com&
client_secret=YOUR_CLIENT_SECRET&
scope=https%3A%2F%2Fdocs.google.com%2Ffeeds%2F+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgoogletalk+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocs&oauth_token_secret=hrUbfZIRxIgpC_AN-arCYDsJ&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Amigration%3Aoauth1

As in the signed-request flow, the response is a refresh token. (For details, see Response).

Validations that are performed on migration requests

When you migrate your code from OAuth 1.0 to OAuth 2.0 and you send a migration request to Google’s OAuth 2.0 token endpoint, all credentials presented in the request are validated.

In addition, scope validation is performed after down-scoping. None of the following are allowed in the list of requested scopes:

  • An empty scope list
  • Any scopes that were not previously granted via OAuth 1.0
  • https://www.google.com/accounts/OAuthLogin
  • https://www.googleapis.com/auth/plus.login

Migrating from Two-Legged OAuth 1.0 to Two-Legged OAuth 2.0

If your app uses the two-legged OAuth 1.0 flow for domain-wide delegation of authority, you must migrate to OAuth 2.0 service accounts. To migrate an app from two-legged OAuth 1.0 to two-legged OAuth 2.0, make the following changes:

  1. Create an OAuth 2.0 service account:
    1. Open the Service accounts page. If prompted, select a project.
    2. Click add Create Service Account, enter a name and description for the service account. You can use the default service account ID, or choose a different, unique one. When done click Create.
    3. The Service account permissions (optional) section that follows is not required. Click Continue.
    4. On the Grant users access to this service account screen, scroll down to the Create key section. Click add Create key.
    5. In the side panel that appears, select the format for your key: JSON is recommended.
    6. Click Create. Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of this key. For information on how to store it securely, see Managing service account keys.
    7. Click Close on the Private key saved to your computer dialog, then click Done to return to the table of your service accounts.

    To enable G Suite domain-wide delegation, follow these steps:

    1. Locate the newly-created service account in the table. Under Actions, click more_vert then Edit.
    2. In the service account details, click expand_more Show domain-wide delegation, then ensure the Enable G Suite Domain-wide Delegation checkbox is checked.
    3. If you haven't yet configured your app's OAuth consent screen, you must do so before you can enable domain-wide delegation. Follow the on-screen instructions to configure the OAuth consent screen, then repeat the above steps and re-check the checkbox.
    4. Click Save to update the service account, and return to the table of service accounts. A new column, Domain-wide delegation, can be seen. Click View Client ID, to obtain and make a note of the client ID.

    Your new service account's client ID, email address, and private key are used in the OAuth 2.0 flow instead of your app's consumer key and consumer secret, which were used in the OAuth 1.0 flow.

  2. The administrator of the Apps domain that runs your app must add your service account's client ID on the Manage API client access page instead of consumer key that was used for the OAuth 1.0 flow. See Managing API client access.
  3. When your app makes authorized API calls, use the OAuth 2.0 service account flow instead of the OAuth 1.0 flow. See the OAuth 2.0 service account documentation.

    The major differences between the OAuth 2.0 flow and OAuth 1.0 flow are:

    • Rather than send your consumer key and signature (and other values) together with your API call, as in the OAuth 1.0 flow, you instead create a signed JSON web token (JWT) that contains your service account email address (and other values), exchange the JWT for an access token, and send the access token together with your API call.

    • Rather than specify the user to act as using the xoauth_requestor_id parameter, as in the OAuth 1.0 flow, you instead specify the user using the sub claim of the JWT.

    For example, the following HTTP request makes a delegated call using OAuth 1.0: 
    GET /m8/feeds/contacts/default/full?xoauth_requestor_id=j.doe%40example.com HTTP/1.1
Host: www.google.com
GData-Version: 3.0
Authorization: OAuth
oauth_version="1.0",
oauth_nonce="1c4fbbe4387a685829d5938a3d97988c",
oauth_timestamp="1328550785",
oauth_consumer_key="example.com",
oauth_signature_method="HMAC-SHA1",
oauth_signature="lqz%2F%2BfwtusOas8szdYd0lAxC8%3D"
    To make the same delegated call using OAuth 2.0, first create a signed JWT with a payload like the following: 
    {
"sub":"j.doe@example.com",
"iss":"SERVICE_ACCOUNT_EMAIL",
"scope":"https://docs.google.com/feeds/",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}
    Then, exchange the signed JWT for an access token: 
    POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=SIGNED_JWT
    Finally, use the access token to call the API: 
    GET /m8/feeds/contacts/default/full HTTP/1.1
Host: www.google.com
GData-Version: 3.0
Authorization: Bearer ACCESS_TOKEN

    You can simplify your implementation of the OAuth 2.0 flow by using the Google API client library for your language. If you use one of the older Google Data API client libraries to call GData APIs, you can use the newer Google API client library to perform the OAuth 2.0 flow, and then call the GData API with the OAuth 2.0 token. The following examples in Python show the same GData request authorized using the two-legged OAuth 1.0 flow and the two-legged OAuth 2.0 flow:

    #
# 2-legged OAuth 1.0
#
import gdata.gauth
import gdata.contacts.client

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'
requestor_id = 'any.user@anydomain.com'

client = gdata.contacts.client.ContactsClient(source='yourCompany-YourAppName-v1')
client.auth_token = gdata.gauth.TwoLeggedOAuthHmacToken(
    CONSUMER_KEY, CONSUMER_SECRET, requestor_id)

# Retrieve user's list of Google Docs
feed = client.GetContacts()
for i, entry in enumerate(feed.entry):
  try:
    print '\n%s %s' % (i+1, entry.name.full_name.text)
  except Exception as ex:
    print '\n%s Failed due to %s' % (i+1, repr(ex))

    #
# 2-legged OAuth 2.0
# Service accounts with domain-wide delegation of authority
#
import gdata.gauth
import gdata.contacts.client
from oauth2client.service_account import ServiceAccountCredentials

SERVICE_ACCOUNT_KEYS = '/path/to/keyfile.json'
requestor_id = 'any.user@anydomain.com'
scopes = ['https://www.google.com/m8/feeds/']

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    SERVICE_ACCOUNT_KEYS, scopes)
delegated_credentials = credentials.create_delegated(requestor_id)

client = gdata.contacts.client.ContactsClient(source='yourCompany-YourAppName-v1')
gdata.gauth.OAuth2TokenFromCredentials(delegated_credentials).authorize(client)

# Retrieve user's list of Google Docs
feed = client.GetContacts()
for i, entry in enumerate(feed.entry):
  try:
    print '\n%s %s' % (i+1, entry.name.full_name.text)
  except Exception as ex:
    print '\n%s Failed due to %s' % (i+1, repr(ex))