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 Developers Console.

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

  1. Open the Credentials page.

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://www.googleapis.com/oauth2/v3/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 Developers Console.

  • client_secret

    Required. This is the OAuth 2.0 client secret, which you get from the Google Developers 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 Using a refresh 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 section of the Developers Console's Permissions page.
      2. Click Create service account.
      3. In the Create service account window, type a name for the service account, and select Furnish a new private key and Enable Google Apps Domain-wide Delegation. Then, click Create.

      Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of this key. You are responsible for storing it securely.

      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://www.googleapis.com/oauth2/v4/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))