Authentication and Authorization in the Google Data Protocol

Warning: This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the Google Data APIs directory, many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, see Google Accounts Authentication and Authorization.

Third-party applications often require limited access to a user's Google Account for certain types of activity. To ensure that user data is not abused, all requests for access must be approved by the account holder. Access control has two components, authentication and authorization.

Authentication services allow users to sign in to your application using a Google Account.

Authorization services let users provide your application with access to the data they have stored in Google applications. Google takes privacy seriously, and any application that requires access to a user's data must be authorized by the user.

Authentication and authorization services are often referred to collectively as auth.

Authentication and authorization for Google APIs allow third-party applications to get limited access to a user's Google account for certain types of activities. This document introduces the available auth mechanisms and describes what each one provides for your application.

• Google Sign-In provides a simple way to let people use their Google credentials to sign-in to your site. It includes a set of tools that are easy to integrate across different devices.
• OAuth 2.0 is an authorization protocol for all Google APIs. OAuth 2.0 relies on SSL for security instead of requiring your application to do cryptographic signing directly. This protocol allows your application to request access to data associated with a user's Google Account.
• Login with OAuth 2.0 (OpenID Connect) authenticates users by having them log in with their Google accounts. This is a replacement for OpenID, and users of OpenID should plan to migrate to Login with OAuth 2.0.

If your application is a gadget (for use in iGoogle or other OpenSocial containers), see the section Authentication for Gadgets.

Note: This document is intended to provide an overview of each authentication method. For detailed information on each method, see the full Google Account Authentication APIs documentation.

See also the Google Accounts API Group for discussion on using the Google Accounts APIs.

OAuth - authorization for web and installed applications

Many Google services allow third-party access to user-generated data, such as Calendar or Documents data, as long as access is authorized by the user. This feature allows users to share and exchange data between their Google applications and third-party applications for a variety of purposes.

Google supports two versions of OAuth for getting authorized access to a user's Google data: OAuth 1.0 and OAuth 2.0, both offering access to both web applications and installed applications.

OAuth 2.0 for web and installed applications

Web applications or installed applications can use the new, simplified OAuth 2.0 protocol to authorize access to data associated with a Google account. For details and examples of how to implement OAuth 2.0 with Google, see our documentation on OAuth 2.0.

OAuth 1.0 for web applications

Web applications that need authorized access to data associated with a Google Account or a Google Apps Account can use Google's implementation of the OAuth API. For complete information about implementing OAuth for web-based applications, including examples, see the OAuth for Web Apps guide, or see the overview in this document.

OAuth 1.0 for installed applications

Applications installed on users' computers and mobile devices can use OAuth to authorize access to data associated with a Google Account. For complete information about implementing OAuth for installed applications, see the OAuth for Installed Applications guide, or see the overview in this document.

Using OAuth with web applications

All Google Data APIs support OAuth, an open standard for authorizing the use of data in web applications. All web applications that make OAuth requests must upload a security certificate and register with Google. See Registration for Web-Based Applications for more information.

The Google Data APIs Client Libraries provide methods to help you use OAuth in your web application. Specifically, there are methods for constructing the request token, authorizing the request token, and exchanging the authorized request token for an access token. The libraries also handle the necessary signing algorithms when making requests to a Google Data service. For extensive examples of how to use OAuth with the Google Data API Client Libraries,see Using OAuth with the Google Data APIs Client Libraries.

The OAuth authorization process

The OAuth authorization process involves a series of interactions between your web application, Google's authorization servers, and the end user.

At a basic level, the process is as follows:

1. Your application requests access and gets an unauthorized request token from Google's authorization server.
2. Google asks the user to grant you access to the required data.
3. Your application gets an authorized request token from the authorization server.
4. You exchange the authorized request token for an access token.
5. You use the access token to request data from Google's service access servers.

When your application initially requests access to a user's data, Google issues an unauthorized request token to your application.

If the user is not already logged in, Google prompts the user to log in. Google then displays an authorization page that allows the user to see what Google service data your application is requesting access to.

If the user approves your application's access request, Google issues an authorized request token. Each request token is valid for only one hour. Only an authorized request token can be exchanged for an access token, and this exchange can be done only once per authorized request token.

By default, access tokens are long-lived. Each access token is specific to the user account specified in the original request for authorization, and grants access only to the services specified in that request. Your application should store the access token securely, because it's required for all access to a user's data.

Getting ready for OAuth

Before you can set up your application to use the Google Authorization service with OAuth, you must complete the following tasks.

Deciding whether to register your web application

To provide your users with additional assurances of the security of their data, you can choose to register your web application with Google and sign your requests with the registered security certificate. Some Google Data API feeds are available to registered applications only. See the documentation for the Google Data API you're interested in to determine if that API only works with registered applications.

Your application must sign each OAuth request it makes. If you choose to use a RSA-SHA1 signature to sign your requests, you must upload a security certificate as part of the registration process.

Alternatively, you can use a HMAC-SHA1 signature to sign your requests. No certificate is required for HMAC-SHA1 signatures. Instead, Google generates an OAuth consumer secret value, which is displayed on your domain's registration page after you have registered.

For more information on the registration process, see Registration for Web Applications.

Determining the scope of the data your application will access

Each Google service sets limits on the access it allows through the Google Data APIs. This access is expressed as a scope value. Some services provide a variety of scope values, to allow a user to choose which applications should have access to which data. For information about the available scope values for the Google service you want to access, see the documentation for that service.

In general, you should request a token for the narrowest scope that includes the data you need. For example, if your application requires access to the user's "All Calendars" feed, you should request a token for the scope http://www.google.com/calendar/feeds/default/allcalendars/full.

Setting up a mechanism to manage OAuth tokens

When you obtain an OAuth access token for a user's data, you must use that access token for all future interactions with the specified Google service on behalf of the user.

Your application should manage token storage securely, including tracking the Google service for which each token is valid. If you require access to more than one Google service, you can obtain multiple access tokens, but no more than ten access tokens per user and application can be outstanding at any time.

If your application supports multiple user accounts, you must keep track of which account each token is associated with. Each OAuth token is specific to the user who authorized access. Your application must be able to associate a token with the correct user. One way to manage this is to issue a cookie to the user before making the token request. After the user grants access to the requested data, Google sends an authorized request token and redirects the user to your application. You can then use your application's cookie to associate the token with the correct user.

Setting up a mechanism to request access to a Google service

Each request to a Google service must be signed, and must include a valid OAuth access token. In general, each request is made in the form of a HTTP GET request, with the access token and signature included in the header. Requests that write new data should use HTTP POST.

For more information on the proper request format for each Google Data API, refer to the documentation for that API.

Implementing OpenID (optional)

If you're implementing OpenID for user authentication, consider using the hybrid protocol to combine the two processes. With OpenID+OAuth, the tasks of getting a request token and authorizing it are handled as part of the OpenID request with OAuth extensions. As with OAuthGetRequestToken, these extensions are used to identify the Google services to be accessed. A successful response to the OpenID request contains an authorized request token. Once this token is received, use OAuthGetAccessToken to exchange it for an access token.

Working with OAuth tokens

To use OAuth, your application must generate well-formed, signed token request calls, and handle the responses, for the following sequence:

1. Get an unauthorized request token (OAuthGetRequestToken)
2. Authorize the request token (OAuthAuthorizeToken)
3. Exchange the authorized request token for an access token (OAuthGetAccessToken)

All OAuth requests must be signed, whether or not your application is registered. For further information, see Signing OAuth Requests.

You can experiment with requesting and receiving authorization tokens in the OAuth Playground.

For detailed documentation, see the OAuth API Reference.

Setting a callback URL

You can specify a value for oauth_callback in an OAuthGetRequestToken request, to determine where Google redirects the user after they authorize your access request. The callback URL can include query parameters. The redirect will include the same query parameters, as well as the authorized request token, which your application must be able to parse.

For example, when supporting multiple languages, you can include a query parameter that identifies the version of the application that a user is viewing. An oauth_callback value of "http://www.yoursite.com/Retrievetoken?Lang=de would result in the redirect "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". Parsing the token and the language parameter ensures that the user is redirected back to the correct version of the site.

If the oauth_callback parameter is not included, Google will direct the user to a web page that displays a verification number (see example), after authorizing your access request. The user must manually return to your application and enter the verification number before you can obtain an authorized request token.

Identifying your application to users

Google normally displays the name of an application when requesting access consent from the user (see example).

If your application is not registered, use the xoauth_displayname parameter in your OAuthGetRequestToken request to specify the name of your application. If that parameter is not specified, Google displays the domain name of the URL provided by the oauth_callback parameter. If no callback URL is provided, Google displays the string "anonymous".

Do not set this parameter if your application is registered. By default, Google shows the display name specified during registration. If you set a display name in your OAuthGetRequestToken request, Google will use this instead of your registered display name, and will include a message that the identity of your application cannot be verified.

Note: To set the xoauth_displayname parameter in the OAuth Playground, check the "Advanced" box before fetching the request token.

Working with Google Apps domains

If your application is designed for users on a hosted Google Accounts domain, consider using the hd parameter when authorizing a token. For more information on the hd parameter, see Handling Users with Multiple Accounts.

More information about OAuth

For detailed information on Google's implementation of OAuth, including how to register your application and construct the necessary OAuth parameters, see these additional resources:

• Using OAuth with the Google Data APIs Client Libraries
• Article: Using OAuth with the Google Data APIs, including a description of the OAuth Playground, an interactive tool for trying out OAuth.
• OAuth for Web Applications (full documentation)
• Registration for Web-Based Applications
• Generating keys and certificates
• OAuth specification

Back to top

Using OAuth with installed applications

All Google Data APIs support OAuth, an open standard for authorizing the use of data in applications. Installed applications need not be registered with Google to use OAuth.

The OAuth authorization process

The OAuth authorization process involves a series of interactions between your application, Google's authorization servers, and the end user.

At a basic level, the process is as follows:

1. Your application requests access and gets an unauthorized request token from Google's authorization server.
2. Google asks the user to grant you access to the required data.
3. Your application gets an authorized request token from the authorization server.
4. You exchange the authorized request token for an access token.
5. You use the access token to request data from Google's service access servers.

When your application initially requests access to a user's data, Google issues an unauthorized request token to your application.

If the user is not already logged in, Google prompts the user to log in. Google then displays an authorization page that allows the user to see what Google service data your application is requesting access to.

If the user approves your application's access request, Google issues an authorized request token. Each request token is valid for only one hour. Only an authorized request token can be exchanged for an access token, and this exchange can be done only once per authorized request token.

OAuth supports installed applications using the unregistered mode. Because there are various methods for obtaining an authorized request token, your app can use OAuth to authorize an application even if the device it's installed on does not have a web browser.

By default, access tokens are long-lived. Each access token is specific to the user account specified in the original request for authorization, and grants access only to the services specified in that request. Your application should store the access token securely, because it's required for all access to a user's data.

Getting ready for OAuth

Before you can set up your application to use the Google Authorization service with OAuth, you must complete the following tasks.

Determining the scope of the data your application will access

Each Google service sets limits on the access it allows through the Google Data APIs. This access is expressed as a scope value. Some services provide a variety of scope values, to allow a user to choose which applications should have access to which data. For information about the available scope values for the Google service you want to access, see the documentation for that service.

In general, you should request a token for the narrowest scope that includes the data you need. For example, if your application requires access to the user's "All Calendars" feed, you should request a token for the scope http://www.google.com/calendar/feeds/default/allcalendars/full.

Setting up a mechanism to manage OAuth tokens

When you obtain an OAuth access token for a user's data, you must use that access token for all future interactions with the specified Google service on behalf of the user.

Your application should manage token storage securely, including tracking the Google service for which each token is valid.

If your application supports multiple user accounts, you must keep track of which account each token is associated with.

Setting up a mechanism to request access to a Google service

Each request to a Google service must be signed, and must include a valid OAuth access token. In general, each request is made in the form of a HTTP GET request, with the access token and signature included in the header. Requests that write new data should use HTTP POST.

For more information on the proper request format for each Google Data API, refer to the documentation for that API.

Working with OAuth tokens

To use OAuth, your application must generate well-formed, signed token request calls, and handle the responses, for the following sequence:

1. Get an unauthorized request token (OAuthGetRequestToken)
2. Authorize the request token (OAuthAuthorizeToken)
3. Exchange the authorized request token for an access token (OAuthGetAccessToken)

All OAuth requests must be signed, whether or not your application is registered. For further information, see Signing OAuth Requests. Installed applications should follow the instructions for an unregistered application.

You can experiment with requesting and receiving authorization tokens in the OAuth Playground.

For detailed documentation, see the OAuth API Reference.

Identifying your application to users

Google normally displays the name of an application when requesting access consent from the user (see example).

Use the xoauth_displayname parameter in your OAuthGetRequestToken request to specify the name of your application. If that parameter is not specified, Google displays the domain name of the URL provided by the oauth_callback parameter. If no callback URL is provided, Google displays the string "anonymous".

Note: To set the xoauth_displayname parameter in the OAuth Playground, check the "Advanced" box before fetching the request token.

Launching a web browser

As part of the OAuth authorization process, your application must make a OAuthAuthorizeToken request. The user must then log in to a Google web page and authorize your application's access request.

• AutoDetect mode should be used for most applications
• Device mode should be used for applications which cannot launch a full web browser.
• Development mode should be used during early development only.

AutoDetect mode

If possible, your application should launch a browser window and make an OAuthAuthorizeToken request to open the Google page. When Google returns the authorized token, your application should detect this and regain focus from the web browser.

This mode requires that you provide a callback URL to which the user is redirected after they authorize your access request. This URL must be provided as the oauth_callback parameter of the OAuthGetRequestToken request, and as the verifier parameter of the OAuthGetAccessToken request.

To improve the user experience, your application should attempt to automatically detect when the user is redirected to this URL, and immediately bring itself to the foreground and make a OAuthGetAccessToken request to complete the OAuth process.

For more information and best practices, see Auto-Detecting Approval.

If your application cannot automatically detect when the user is redirected to the callback URL, or cannot bring itself to the foreground, the callback URL should display a page that explains how to bring your application to the foreground and how to initiate the OAuthGetAccessToken request from within your application.

Device mode

If your application cannot launch a full web browser, it is also possible for rich-client devices to authorize without a web browser.

This mode allows a developer to set up a website where a user can authorize the request for access. After authorization, the user is given a code generated by Google, and redirected to the developer's site. This site should explain to the user how to input the code into their device to complete the authorization process.

Development mode

This mode is recommended for use during the early development of an application only.

As in the AutoDetect mode, your application must launch a browser, and the user must authorize your request. However, instead of creating a webpage for the callback URL, you can set the value of the oauth_callback parameter to "oob" (out of band).

In that case, after the user authorizes your request, Google directs the user to a Google Accounts page that displays a verification number (see example).

The user must return to your application and enter the verification number, before you can make a OAuthGetAccessToken request.

More information about OAuth

For detailed information on Google's implementation of OAuth, including how to register your application and construct the necessary OAuth parameters, see these additional resources:

• Using OAuth with the Google Data APIs Client Libraries
• Article: Using OAuth with the Google Data APIs, including a description of the OAuth Playground, an interactive tool for trying out OAuth.
• OAuth for Installed Applications (full documentation)
• Generating keys and certificates
• OAuth specification

Back to top

Using AuthSub for authorization

AuthSub is a Google proprietary authorization API, available as an alternative to OAuth for most Google APIs. You should avoid using AuthSub if possible. If you already have applications that use AuthSub, you should migrate to OAuth or the hybrid protocol.

The AuthSub authorization process

Authorization with AuthSub involves a sequence of interactions between three entities: the web application, Google services, and the user. This diagram illustrates the sequence:

1. When the web application needs to access a user's Google service, it makes an AuthSub call to Google's Authorization Proxy service.
2. The Authorization service responds by serving up an Access Request page. This Google-managed page prompts the user to grant/deny access to their Google service. The user may first be asked to log into their account.
3. The user decides whether to grant or deny access to the web application. If the user denies access, they are directed to a Google page rather than back to the web application.
4. If the user grants access, the Authorization service redirects the user back to the web application. The redirect contains an authorization token good for one use; it can be exchanged for a long-lived token.
5. The web application contacts the Google service with a request, using the authorization token to act as an agent for the user.
6. If the Google service recognizes the token, it supplies the requested data.

Working with AuthSub

Incorporating AuthSub into your web application requires these tasks:

1. Decide whether or not to register your web application.

   Registered web applications have the advantage of being recognized by Google; the standard caveat displayed to users on the Google login page is modified or omitted. In addition, registered web applications are identified with a descriptive name rather than merely the calling URL. Keep in mind that some Google services allow only limited access to unregistered web applications. If you choose to register, use this automated registration process.

   If you register, you can also provide a security certificate and keys. Registered web applications with a certificate on file are able to acquire secure tokens for use when requesting data from a Google service. (They can also use non-secure tokens if necessary.)

2. Decide what type of tokens to use and how to manage them.

   An authorization token received from Google is intended to be used for all future interactions with the specified Google service for that user. The type of token you choose to use--single-use or session--depends on the type of interactions your web application will have with a Google service. For example, a single-use token may be sufficient if the interaction is a one-time or rare event.

   If you choose to get session tokens and use them regularly to access the Google service, your web application will need to manage token storage, including tracking the user and Google service the token is valid for. Google Accounts is not set up to manage large numbers of tokens, and in fact does not allow more than ten valid tokens (per user, per web application) to be outstanding at any one time. This limitation allows a web application to get multiple tokens to cover different services, if necessary; it does not support getting a new token each time the web application needs to access a Google service. If you decide to store session tokens, the tokens should be treated as securely as any other sensitive information stored on the server.

   Alternatively, you can choose to get fresh tokens on a regular basis as long as you set up a token revocation mechanism. Your application would need to revoke the existing token before requesting another. In this scenario, the user would be required to log in and grant access each time a new token is requested.

3. Determine the scope required by the Google service to be accessed.

   Each Google service determines how much and what type of access it will allow. This access is expressed as a scope value. A service's scope may be a simple URL identifying the entire service, or it may specify more restricted access. Some services severely limit access, such as allowing read-only access to limited information. To get the allowed scopes for the Google service you want to access, refer to the documentation for that service. You should request the most tightly scoped token possible. For example, if attempting to access Gmail's Atom feed feature, use the scope "http://www.google.com/calendar/feeds/", not "http://www.google.com/calendar/". Google services are much more restrictive with large-scope requests.

4. Set up a mechanism to request and receive an authorization token.

   The mechanism must generate a well-formed AuthSubRequest call, including specifying the appropriate next and scope URL values (determined in step 3). If you are using secure tokens and/or are managing session tokens, the request must include values for these variables as well.

   The next URL can include query parameters. For example, when supporting multiple languages, include a query parameter that identifies the version of the web application the user is viewing. A next value of http://www.yoursite.com/Retrievetoken?Lang=de would result in the redirect http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. Parsing the token and the Lang parameter ensures that the user is redirected back to the correct version of the site.

   In certain circumstances, using the hd parameter can help streamline your users' experience when they are asked to grant access on the Google Accounts site. In most cases, the process is a simple matter of logging into their account and choosing whether or not to grant access. Users who have more than one Google Account (a regular gmail account and/or one or more Google Apps hosted accounts), however, may need to follow the extra "universal login" process to to identify which account they wish to have accessed. If your application is designed for one particular managed domain, you can eliminate these extra steps by using this parameter to identify that domain. You can also use the hd parameter if your application accesses services that are not available on hosted accounts--setting the value to 'default' will limit authorization to regular accounts only. When the hd value is set, Google will automatically select the correct account for authorization.

   The token mechanism must be equipped to parse the redirect received from Google, which contains the single-use token, and take action with it. Because authorization tokens are specific to a user, your application must be able to associate a token with its user. The preferred option is to issue a cookie to the user before making the token request. Then, when Google redirects the user back to your site with an appended token, your application can read the cookie and associate the token with the correct user identification.

5. Set up mechanisms to request session tokens and store or revoke them, if relevant.

   Depending on what token management decisions you made in step 2, you may need to create mechanisms to get and revoke session tokens (AuthSubSessionToken and AuthSubRevokeToken). To test session and revocation mechanisms, use AuthSubTokenInfo, which indicates whether a given token is valid or not. If storing tokens, the application must track both the user ID and the service (scope) covered by the token.

6. Set up a mechanism to request access to a Google service.

   Refer to documentation for the Google service for information on the proper request format. All requests to a Google service must include a valid authorization token. In general, a request to a Google service is in the form of an HTTP GET (or POST if writing new data), with the token referenced in the request header.

   The request header should take the following form:

   Authorization: AuthSub token="token"

   where token is the authorization token, single-use or session, received from Google in response to an AuthSub request. If the token is secure, it must be accompanied by a digital signature. See "Signing requests" for instructions and examples.

   The example below illustrates a request header for a call to the Google Calendar feed service. This request contains a non-secure token:

   GET /calendar/feeds/default/private/full HTTP/1.1
   Content-Type: application/x-www-form-urlencoded
   Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
   User-Agent: Java/1.5.0_06
   Host: www.google.com
   Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
   Connection: keep-alive

More information about AuthSub

For information on AuthSub, including registering your application with Google and a detailed explanation of exchanging a one-time token for a session token, see these additional resources:

• AuthSub Authentication for Web Applications (full documentation)
• Using AuthSub with the Google Data APIs Client Libraries
• Generating keys and certificates (secure AuthSub)
• Signing Requests with AuthSub (secure AuthSub)
• Registration for Web-Based Applications

Back to top

Using ClientLogin for authorization

ClientLogin is a Google proprietary authorization API, available as an alternative to OAuth for most Google APIs. You should avoid using ClientLogin if possible. If you already have applications that use ClientLogin, you should migrate to OAuth or the hybrid protocol.

Authentication for Installed Applications: ClientLogin

ClientLogin allows your users to log into their Google account from inside your application. The application then contacts Google with the login data and requests access to a specified Google Data API. Once the login information has been successfully authenticated, Google returns a token, which your application will reference each time it requests access to the user's account, such as to get or post data. The token remains valid for a set length of time, defined by whichever Google service you're working with.

Note: The Google Data APIs Client Libraries provide methods to help you use ClientLogin in your installed applications. Specifically, there are methods for acquiring an authentication token, handling CAPTCHA challenges, recalling the auth token for later use, and sending the correct Authorization header with every request. If you are working with one of the libraries, see Using ClientLogin with the Google Data APIs Client Libraries.

The ClientLogin authorization process

Authorization with ClientLogin involves a sequence of interactions between three entities: the installed application, Google services, and the user. This diagram illustrates the sequence:

1. When the third-party application needs to access a user's Google service, it retrieves the user's login name and password.
2. The third-party application then makes a ClientLogin call to Google's Authorization service.
3. If the Google Authorization service decides additional vetting is necessary, it returns failure response with a CAPTCHA token and challenge, in the form of a URL for a CAPTCHA image.
4. If a CAPTCHA challenge is received, the third-party application displays the CAPTCHA image for the user and solicits an answer from the user.
5. If requested, the user submits an answer to the CAPTCHA challenge.
6. The third-party application makes a new ClientLogin call, this time including the CAPTCHA answer and token (received with the failure response).
7. On a successful login attempt (with or without CAPTCHA challenge), the Google Authorization service returns a token to the application.
8. The application contacts the Google service with a request for data access, referencing the token received from the Google Authorization service.
9. If the Google service recognizes the token, it supplies the requested data access.

Using ClientLogin

Use this interface in your installed application to programmatically access a user's Google account. After collecting login information from the user, call ClientLogin to request access to the user's account. Once the login information has been successfully authenticated, Google returns a token, which your application will reference each time it requests access to the user's account. The token remains valid for a set length of time, which is defined by whichever Google service you're working with.

Incorporating ClientLogin into your application requires these tasks:

1. Create a UI element to capture login data from the user.

   The UI needs to solicit a user name (email address including domain) and password. The UI should also be capable of displaying a CAPTCHA image using the URL received from Google, if one is required, and soliciting a correct answer from the user. Ideally, your UI will include a link to Google Accounts login page ("https://www.google.com/accounts/Login") in the event that the user needs to sign up for a new account or do other account maintenance.

2. Write code to generate a well-formed HTTPS POST ClientLogin request and transmit it.

   This code needs to contain logic to handle a CAPTCHA challenge and include both the logintoken and logincaptcha parameters. The application should also be able to detect when the user omits required information--or repeats incorrect data after a login failure--and display an error without sending a superfluous request.

3. Handle responses from Google.

   There are four possible responses to a login request:

   • success (an HTTP 200)
   • failure (an HTTP 403) with an explanatory error code
   • invalid request, generally resulting from a malformed request
   • failure with a CAPTCHA challenge

   A success response contains an authorization token labeled "Auth". This token must be included in all subsequent requests to the Google service for this account. Authorization tokens should be closely guarded and should not be given to any other application, as they represent access to the user's account. The time limit on the token varies depending on which service issued it.

   A failure response includes one or more error codes and a URL with the error message that can be displayed for the user. Please note that ClientLogin does not differentiate between a failure due to an incorrect password or one due to an unrecognized user name (for example, if the user has not yet signed up for an account). Your application needs to handle all possible error messages as appropriate.

   A failure response with a CAPTCHA challenge means that Google has decided, for whatever reason, that additional security measures should be taken. This response is accompanied by a CAPTCHA image URL and a token representing the specific CAPTCHA challenge.

4. Handle a CAPTCHA challenge from Google.

   To handle the challenge, the application must display the CAPTCHA image and solicit an answer from the user. To display the CAPTCHA image, use the value of CaptchaUrl returned with the failure response, prefixing it with the Google Accounts URL: "http://www.google.com/accounts/". Once the user provides an answer, the application should resend the login request, this time including the CAPTCHA token (logintoken) and the user's answer (logincaptcha). Google validates the user's answer before authorizing access to the account.

   There is an alternative for developers who do not want to manage the process's of getting and transmitting a user CAPTCHA response. In response to a CAPTCHA challenge, the application can direct the user to the Google hosted page: "https://www.google.com/accounts/DisplayUnlockCaptcha". Once the user has successfully responded to the challenge, the Google server trusts the computer in use. The application can then resend the original login request to obtain the authorization token.

Note: Google does not validate the login attempt prior to issuing a CAPTCHA challenge. This means a login attempt could fail even after a CAPTCHA challenge.

* CAPTCHA is a trademark of Carnegie Mellon University

Back to top

Authentication for Gadgets

OAuth Proxy

If you're building a gadget using the standard Gadgets API, you can leverage a feature of the gadget platform called the OAuth Proxy to access the Google Data APIs. OAuth (described above) is an authentication standard that allows users to access their private data in a gadget hosting service such as iGoogle, MySpace, or Orkut, or share their data with another website or gadget. The OAuth Proxy is designed to make development easier for gadget developers by hiding many of OAuth's authentication details. The Proxy is based on an open-source project called Shindig, which is an implementation of the gadget specification.

Note: The OAuth Proxy is only supported for gadgets that use the gadgets.* API and run in OpenSocial containers. It is not supported for the legacy gadgets API.

Authentication flow

Your gadget must obtain an OAuth token before it can access a user's data. The OAuth Proxy manages the authentication flow for you. The first time a user installs your gadget, the following process takes place:

1. Your gadget loads for the first time and attempts to access the user's data using one of the Google Data APIs.
2. The request fails because the user hasn't granted access. The response object contains a URL (in response.oauthApprovalUrl) for the OAuth approval page. Your gadget should provide a method to launch a new window with that URL.
3. On the approval page, the user chooses to grant or deny access to your gadget. If successful, the user is taken to the oauth_callback page you specify. For the best user experience, use http://oauth.gmodules.com/gadgets/oauthcallback.
4. Next, the user closes the popup window. To notify your gadget that the user has approved, you can use a popup handler to detect the approval window closing. Alternatively, your gadget can display a link (e.g. "I've approved access") for the user to click after this window closes.
5. Your gadget attempts to access the Google Data API a second time by re-requesting the user's data. This attempt is successful.
6. Your gadget is authenticated and can begin operating normally.

Gadget setup

To access one or more of the Google Data APIs, you first need to tell your gadget to use OAuth as the authentication method. Add an <OAuth> element in the <ModulePrefs> section of your gadget's XML:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

In this section, only change the following query parameters:

scope

A required parameter in the Request URL. Your gadget can access data from the scope(s) used in this parameter. In this example, the gadget can access Blogger and Calendar data. A gadget can request data for a single scope or multiple scopes, as this example does.

oauth_callback

An optional parameter in the Authorization URL. The OAuth approval page redirects to this URL after the user has approved access to data. You should set this parameter to http://oauth.gmodules.com/gadgets/oauthcallback to provide the best user experience when users install your gadget. That page provides a snippet of JavaScript that automatically closes the popup window. Alternatively, you can set this parameter to point to your own "approved" page, or you can simply leave the parameter blank.

Accessing an authenticated Google Data API feed

Once your gadget has authenticated the user, accessing a Google Data API is straightforward with the Google Data APIs JavaScript client library. For information on how to use the library in the OAuth Proxy, see Using the JavaScript Client Library.

More information about Gadgets

For complete information on creating Google Data API Gadgets, including details on the OAuth Proxy, an article on how to get started, and the gadgets.* spec, see these additional resources:

• Using the JavaScript Client Library
• Creating a Google Data APIs Gadget (article)
• Writing OAuth Gadgets (full gadget documentation)
• Gadgets API documentation

Back to top