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:
Revoke the access token associated with your application for your user
account:
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.
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:
The process is triggered when an OAuth 1.0 consumer (your application)
sends a migration request
to Google’s OAuth 2.0 token endpoint.
The credentials in the migration request are validated.
An OAuth 2.0 refresh token is issued to your application in the
response to your migration request.
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:
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.
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).
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:
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:
Click addCreate 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.
The Service account permissions (optional) section that follows is not required. Click
Continue.
On the Grant users access to this service account screen, scroll down to the
Create key section. Click addCreate key.
In the side panel that appears, select the format for your key: JSON is recommended.
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.
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:
Locate the newly-created service account in the table. Under Actions, click
more_vert then Edit.
In the service account details, click expand_moreShow domain-wide delegation, then ensure the Enable G Suite Domain-wide Delegation
checkbox is checked.
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.
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.
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.
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:
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))
OAuth reference
Getting and upgrading an OAuth 1.0 token (deprecated)
Before you can access a user's data, you must do the following:
Exchange the authorized request token for an access token, using
OAuthGetAccessToken.
Version Update: OAuth v1.0 to OAuth v1.0a
Google's OAuth 1.0 endpoints are updated for OAuth v1.0a. This update involves two major changes:
A new parameter, oauth_verifier, is now required by the OAuthGetAccessToken endpoint. This parameter takes a verification code, which is generated by Google once a user has granted access to the third-party application. The verification code is returned one of two ways:
If the third-party application supplies a callback URL, Google redirects the user back to the application after a successful call to OAuthAuthorizeToken, with query parameters containing token, token secret, and verifier.
If the third-party application does not supply a callback URL, Google displays a web page to the user containing the verification code. This scenario allows applications that can't process redirects to use this OAuth; it is assumed that these applications will provide a way for users to enter the verification code into the application.
The parameter oauth_callback has been moved from the OAuthAuthorizeToken endpoint to the OAuthGetRequestToken endpoint. This enables authorization providers, like Google, to confirm that a URL redirect back to the third-party application can be handled.
For backward compatibility, Google continues to support applications using OAuth version 1.0, recognizing calls to OAuthAuthorizeToken with the oauth_callback parameter and calls to OAuthGetAccessToken without a verification code. Because of the lack of a verification code, however, applications using v1.0 will trigger the yellow warning box displayed to users on the Request Access page (see example).
OAuthGetRequestToken
Contact Google for a request token. Google verifies that the requesting application has been registered with Google or is using an approved signature (in the case of installed applications). The request token acquired with this request must be first authorized by the end user and then exchanged for an access token. A request token cannot be used to get access to a Google service.
Send a request to: https://www.google.com/accounts/OAuthGetRequestToken with the following query parameters:
Parameter
Description
oauth_consumer_key
(required) Domain identifying the third-party web application. This is the domain used when registering the application with Google.
oauth_nonce
(required) Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks.
oauth_signature_method
(required) Signature algorithm. The legal values for this parameter "RSA-SHA1" or "HMAC-SHA1". Google does not support "PLAINTEXT".
oauth_signature
(required) String generated using the referenced signature method. See Signing requests.
oauth_timestamp
(required) Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
scope
(required) URL identifying the service(s) to be accessed. The resulting token enables access to the specified service(s)
only. Scopes are defined by each Google service; see the service's documentation for the correct value. To specify more than one scope, list each one separated with a space. This parameter is not defined in the OAuth standards; it is a Google-specific parameter.
oauth_callback
(required) URL the user should be redirected to after access to a Google service(s) is granted (in response to a call to OAuthAuthorizeToken). The response to this OAuthGetRequestToken call verifies that Google handles a callback URL. The callback URL can include url-encoded query parameters.
To trigger an alternative sequence, in which Google displays a success page with a verification code that the user must then supply to the third-party application, use the value oob. In the subsequent call to OAuthGetAccessToken, the parameter verifier must be set to this value.
oauth_version
(optional) The OAuth version used by the requesting web application. This value must be "1.0"; if not provided, Google assumes version 1.0 is in use.
xoauth_displayname
(optional) String identifying the application. This string is displayed to end users on Google's authorization confirmation page. For registered applications, the value of this parameter overrides the name set during registration and also triggers a message to the user that the identity can't be verified. For unregistered applications, this parameter enables them to specify an application name, In the case of unregistered applications, if this parameter is not set, Google identifies the application using the URL value of oauth_callback; if neither parameter is set, Google uses the string anonymous.
Depending on the type of request sent, these parameters can be placed in:
Authorization header of a GET or POST request. Use "Authorization: OAuth". All parameters listed above can go in the header, except for scope and xoauth_displayname, which must go either in the body or in the URL as a query parameter. The example below puts them in the body of the request.
Body of a POST request. The content type must be "Content-Type: application/x-www-form-urlencoded".
If the request for a request token is successful, Google responds with an HTTP 200 OK message containing an OAuth request token, a token "secret", and confirmation that Google handles a callback URL.
A token request may be rejected by Google if the request is malformed or if Google has reason to believe
the requestor is not acting in good faith. If the request is not successful, Google returns the following error:
HTTP 400 Bad Request: in the case of an unsupported or missing parameter, an unsupported oauth_signature_method,
or other error in the request format or content.
OAuth 1.0 sample response
This example illustrates an OAuth request token returned in the response header. At this point, the request token cannot be used to request data from the Google service; it must be authorized by the Google Authorization service.
Call the Google Authorization service at https://www.google.com/accounts/OAuthAuthorizeToken with the following query parameters:
Parameter
Description
oauth_token
(required) Request token obtained from Google.
hd
(optional) String value identifying a particular hosted domain account to be accessed (for example, 'mycollege.edu'). Use "default" to specify a regular Google account ('username@gmail.com'). This is a Google-specific parameter.
hl
(optional) An ISO 639 country code identifying what language the approval page should be translated in (for example, 'hl=en' for English). The default is the user's selected language. This is a Google-specific parameter.
btmpl
(optional) Forces a mobile version of the approval page. The only accepted value is "mobile". This is a Google-specific parameter.
OAuth 1.0 sample request
This example shows a request for authorization:
GET https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=ab3cd9j4ks73hf7g&hd=mycollege.edu&hl=en&btmpl=mobile
OAuth 1.0 request authorization response
If Google accepts the request, the user is redirected to a Google login page, where:
The user is asked to verify access to their Google account. Because it's possible for someone to have more than one Google-affiliated account (a regular Google account and one or more hosted accounts), in some cases the user also must specify which account to grant access to. There are two possible paths your users may experience:
If you've used the hd parameter to specify an account domain, the user is asked to log in to that account, if they aren't already logged in. For more information on the hd parameter, see Handling users with multiple accounts.
If you don't use the hd parameter, the user is put into a "universal login" path, which walks the user through selecting and logging into any type of Google account. Because the universal login process is still in beta, we recommend you use the hd parameter whenever possible. We're continuing to improve the user experience in this area.
Once the user has selected an account
and verified access, the Authorization service displays the Google Access Request page (see example). This page:
Identifies the third-party application requesting access. By default, Google uses the value of xoauth_displayname in the initial OAuthGetRequestToken request and displays a message indicating that the application's identity cannot be verified. If no display name is specified and the application is registered with Google, Google uses the name specified during registration. If the application is not registered, Google uses the oauth_callback URL, if set; if it is not set, Google uses the string anonymous.
Informs the user that a third party wants access to their Google service.
Identifies the Google service(s) to be accessed.
Prompts the user to confirm that it's OK to give the third party access to their Google service.
If the user grants access, the referenced request token is authorized.
If a callback URL is provided, Google redirects the user to the URL specified in the web application registration, and the request token and verification number are included as query parameters. If no callback URL is provided, Google displays a message to the user with a verification code (see example).
Note: The return of a verification code does not indicate that a request token has been authorized. If a request token has not been authorized, then requests to exchange it for an access token will fail.
OAuth 1.0 sample response
This example illustrates the format of a Google redirect back to the web application with a request token and verification code.
The token is a text string, up to 256 bytes.
Google redirects with token and verifier regardless of whether the token has been authorized.
OAuthGetAccessToken
Contact Google to exchange an authorized request token for an access token. The access token received in response to this request is used to request data from a Google service.
Send an HTTP request to: https://www.google.com/accounts/OAuthGetAccessToken with the following query parameters:
Parameter
Description
oauth_consumer_key
(required) Domain identifying the third-party web application. This is the domain used when registering the application with Google. This value must be the same as the one provided in OAuthGetRequestToken.
oauth_token
(required) Authorized request token.
oauth_verifier
(required) Verification code issued by Google in response to a successful call to OAuthAuthorizeToken. The verification code is either returned as a query parameter in the redirect URL or is displayed in a web page shown to the user once access has been granted, which the user must supply to the application in some way.
oauth_signature_method
(required) Signature algorithm. The legal values for this parameter "RSA-SHA1" or "HMAC-SHA1". Google does not support "PLAINTEXT".
oauth_signature
(required) String generated using the referenced signature method. See Signing requests.
oauth_timestamp
(required) Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
oauth_nonce
(required) Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks.
oauth_version
(optional) The OAuth version used by the requesting web application. This value must be "1.0"; if not provided, Google assumes version 1.0 is in use.
Depending on the type of request sent, these parameters can be placed in:
Authorization header of a GET or POST request. Use "Authorization: OAuth".
Body of a POST request. The content type must be "Content-Type: application/x-www-form-urlencoded".
Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity.
OAuth 1.0 access token response
If the request for an access token is successful, Google responds with an HTTP 200 OK message containing an OAuth access token and a token "secret".
A token request may be rejected by Google if the request is malformed or if Google has reason to believe
the requestor is not acting in good faith. If the request is not successful, Google returns the following error:
HTTP 400 Bad Request:in the case of an unsupported or missing parameter, an unsupported signature method,
or other error in the request format or content. This error is also returned if the referenced request token has not been authorized.
OAuth 1.0 sample response
This example illustrates an OAuth access token returned in the response header.
All calls requesting or using an OAuth token must be signed, regardless of whether your application is registered with Google or not. This includes calls to OAuthGetRequestToken, OAuthGetAccessToken, and all requests made to Google services. This section describes how to generate a signature for the requests. For more detailed information on this process, see the OAuth specification, Section 9.
Each request must specify the signature method in use (oauth_signature_method). Unregistered applications should use HMAC-SHA1. Registered applications can use either RSA-SHA1 and HMAC-SHA1.
Construct a signature "base string", which consists of a concatenation of three request elements:
The HTTP request method.
The base URL the request is being sent to. This URL should not include any query parameters. When signing calls to Google services, refer to the OAuth specification, Section 9.1.2, for relevant instructions.
A normalized string of the parameters in the request (excluding the oauth_signature parameter). This includes parameters sent in the request header or body, as well as query parameters added to the request URL. To normalize the string,
sort the parameters using lexicographical byte value ordering. For more details on normalizing this string, see Section 9.1.1 of the OAuth specification.
Generate an oauth_signature using one of the following sequences:
If your application is not registered, select HMAC-SHA1 and use the following key and secret:
consumer key: anonymous
consumer secret: anonymous
If your application is registered and you're using RSA-SHA1, use the private key corresponding to the certificate uploaded to Google during registration.
If your application is registered and you're using HMAC-SHA1, use the OAuth "consumer secret" value generated during registration; this value is displayed on your domain's registration page.
OAuth 1.0 example requests
This example shows a registered application using the Google Calendar API to retrieve a user's list of calendars at http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime. The example assumes you have
a valid OAuth access token.
Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity only. The ordering of the oauth_* parameters does not matter in the Authorization header.
Handling users with multiple accounts (deprecated)
In most cases, the process of getting access confirmation from an end user is a simple matter of the user logging into their account and choosing whether or not to grant access. For users who have more than one Google Account, however, (a regular Google account and/or one or more hosted accounts), users may need to follow additional "universal login" steps to identify which account they wish to grant access to.
In certain circumstances, using the hd parameter with OauthAuthorizeToken can help streamline your users' experience. If your application is designed for one particular managed domain, you can eliminate the extra login steps by using this parameter to specify the only domain that's valid for your application. You can also use the hd parameter if your application accesses services that are not available to hosted accounts; setting the value to 'default' will limit authorization to regular accounts only. Using this parameter helps limit the account choices for the user, preventing them from making invalid choices.
Testing and debugging OAuth 1.0 requests (deprecated)
Google's OAuth Playground tool helps to debug problems, check your own implementation, and experiment with the Google Data APIs.
Illustrates the OAuth authorization flow:
Fetches a request token
Authorizes a request token
Upgrades the token to an access token.
Helps with debugging OAuth requests:
Displays the correct signature base string for each request.
Displays the correct Authorization header for each request.
Demonstrates how to use an oauth_token to interact with an authorized Google Data feed.
Tests your own oauth_consumer_key (your registered domain), RSA private key, and HMAC consumer secret.
Lets you experiment with the Google Data APIs:
Uses GET, PUT/POST, or DELETE to manipulate data.
Allows you to view an authorized feed directly in your browser.
Identifies what Data feeds are available to your oauth_token.
OAuth access tokens can be revoked either manually or programmatically.
To manually revoke an OAuth 1.0 token (for Google account holders):
Users can make changes to their Google Accounts settings at https://www.google.com/accounts/. For Google Apps (hosted) domain accounts, go to https://www.google.com/a/yourdomain.com/ManageAccount.
Click the link "Change authorized websites".
In the list of authorized domains displayed, locate the domain to be revoked. Click the "Revoke Access" link next to the domain name.
Access to the user account for that domain will no longer be allowed. Users must explicitly approve subsequent access requests, using the same process as they originally granted access.
To programmatically revoke an OAuth 1.0 token (for third-party applications), send a request to AuthSub's AuthSubRevokeToken endpoint (deprecated) with
the necessary signed OAuth request.