Google Accounts Authentication and Authorization

AuthSub for Web Applications

Important: AuthSub has been officially deprecated as of April 20, 2012. It will continue to work as per our deprecation policy, but we encourage you to migrate to OAuth 2.0 as soon as possible.

Web applications that need to access services protected by a user's Google or Google Apps (hosted) account can do so using the Authorization Proxy service. To maintain a high level of security, the proxy interface, called AuthSub, enables the web application to get access without ever handling their users' account login information. Before using, verify that the Google service to be accessed supports the Authorization service.

Note: If your application uses the JavaScript client library for the Google Data API, you'll need to use the library's methods to access the AuthSub for JavaScript interface.

Developers can opt to handle authorization with either secure tokens or non-secure tokens. To use secure tokens, the web application must be registered with Google and have a certificate on file; if registered, the web application can secure all requests with a digital signature.

This page describes how to incorporate use of the Authorization service with AuthSub into your web-based application. See also the Google Accounts API Group for discussions on using the Accounts API. For information on Google's other account authorization solutions, see the Getting Started guide.

Contents

  1. The AuthSub authorization process
    1. Tokens and token management
    2. Registration
  2. Working with AuthSub
  3. The AuthSub interface
    1. AuthSubRequest
    2. AuthSubSessionToken
    3. AuthSubRevokeToken
    4. AuthSubTokenInfo
  4. Special topics
    1. Signing requests
    2. Single sign-on

Audience

This document is aimed at programmers who are developing web applications that communicate with their users' Google services and who want to implement a programmatic way to gain access. It assumes you've read up on the service(s) being accessed and are aware of any access/authorization issues involved. You need to know some service-specific details when incorporating use of the Authorization proxy service.

Example scenario

Users of Google Calendar manage their schedules, add, update, or delete events, and share calendar information. In this scenario, you want your application to access your users' Google Calendar data and manipulate that data on their behalf.

To do this, your application needs to get access to your user's Calendar account. Before accessing the Calendar service, the application must request authorization from Google. It does so by calling the Google Authorization URL and supplying some required information, such as the name of the service to be accessed. A Google page is displayed that prompts the user to either consent or refuse to provide access to their Google Calendar account. If the user consents, Google redirects the user back to your web application and supplies an authorization token for the requested service. Your web application can then make requests directly to the Google service, referencing the token in each request.

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:

Authorization process

  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.

Tokens and token management

Each authorization token is specific to one user account but can cover multiple services for that account. Tokens may be further limited as to scope; for example, individual services may limit access to certain types of data or activity, such as read-only access.

You can opt to use one-time-use tokens or session tokens, depending on how you decide to manage token usage in your application. A one-time-use token allows the application to make a single call to the Google service, while a session token lets the application make unlimited calls to the Google service. Session tokens do not expire. When using session tokens, your application should store the session token for each user rather than requesting a new one each time it needs to access a Google service. For other token management options, see Working with AuthSub.

Registered web applications can specify a secure token in their AuthSub request. When calling a Google service with a secure token, the application must digitally sign the request, including both the token and the signature in the header of a request. The request can include a timestamp to enhance security, protecting against replay attacks. For more information about using secure tokens, see Signing requests. Other than these variations, the AuthSub request process is the same when using secure and non-secure tokens.

Note: Some Google services may allow access only to web applications that are registered and use secure tokens.

Registration

If you're using AuthSub, you can opt to register your web application with Google and provide enhanced security for your users by creating a security certificate. Although most Google services allow access to unregistered applications, some require more secure access. For more information on the registration process, see Registration for Web Applications.

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

The AuthSub interface

The AuthSub interface provides several methods for acquiring and managing authorization tokens. Once a web application has received a token, it can request access to a Google service. For information on forming the access request to a Google service, see the documentation for the service.

The following methods make up the AuthSub interface:

AuthSubRequest. A call to this method sends the user to a Google Accounts web page, where the user is given the opportunity to log in and grant Google account access to the web application. If successful, Google provides a single-use authorization token, which the web application can use to access the user's Google service data.

AuthSubSessionToken. A call to this method allows the web application to exchange a single-use token for a session token.

AuthSubRevokeToken. A call to this method revokes a session token. Once a token is revoked it is no longer valid.

AuthSubTokenInfo. A call to this method verifies whether a specified session token is valid and returns data associated with the token.

AuthSubRequest

Call AuthSubRequest to acquire single-use authorization. AuthSubRequest is called as a URL; make a request to https://www.google.com/accounts/AuthSubRequest with the following query parameters:

Parameter Description
next (required) URL the user should be redirected to after a successful login. This value should be a page on the web application site, and can include query parameters.
scope (required) URL identifying the service(s) to be accessed; see documentation for the service for the correct value(s). The resulting token enables access to the specified service(s) only. To specify more than one scope, list each one separated with a space (encodes as "%20").
btmpl (optional) Forces a mobile version of the approval page. The only accepted value is "mobile".
hd (optional) String value identifying a particular Google Apps (hosted) domain account to be accessed (for example, 'mycollege.edu'). Use "default" to specify a regular Google account ('username@gmail.com').
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.
secure (optional) Boolean flag indicating whether the authorization transaction should issue a secure token (1) or a non-secure token (0). Secure tokens are available to registered applications only.
session (optional) Boolean flag indicating whether the one-time-use token may be exchanged for a session token (1) or not (0).

Sample requests

The first example requests a single-use token for the Google Calendar and Picasa services. The second example requests a secure token for the Google Calendar service that can be exchanged for a session token.

https://www.google.com/accounts/AuthSubRequest?
   next=http%3A%2F%2Fwww.yourwebapp.com%2Fshowcalendar.html
   &scope=http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2F%20http%3A%2F%2Fpicasaweb.google.com%2Fdata
   &session=0
   &secure=0

~~~~~~~~~~~~~~~~

https://www.google.com/accounts/AuthSubRequest?
   next=http%3A%2F%2Fwww.yourwebapp.com%2Fshowcalendar.html
   &scope=http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2F
   &session=1
   &secure=1

AuthSubRequest response

If Google accepts the request:

  1. 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 When to use the hd parameter.)
    • If you don't use the hd parameter, the user is placed on 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.
  2. Once the user has selected an account and verified access, the Authorization service displays the Google Access Request page (see example). This page:
    • Informs the user that a third party wants access to their Google service.
    • Identifies both the third party and the Google service to be accessed.
    • Indicates that the request is for one-time access (if session is set to zero or not specified).
    • Provides information on the level of security being used by the third party.
    • Prompts the user to confirm that it's OK to give the third party access to their Google service.
    • Note: The example shown illustrates the response to an AuthSub request from a non-registered web site. The response to a request from a registered application omits the yellow warning statement.

  3. If the user does not consent to the access request, they are redirected to a Google page (see example) instead of directly back to the web application page.
  4. If the user grants access, Google redirects the user to the URL specified in the AuthSub request next parameter. The redirect URL contains the authorization token. All requests for access to a Google service must include a valid authorization token, specific to both the service and the user.

An AuthSub 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. It could also be rejected if the request's scope is not sufficiently narrow. If the request is rejected, the user is not redirected back to the requestor's web page; instead, a Google page is displayed indicating that the request failed.

Sample responses

This example illustrates the format of a Google redirect back to the web application with an authorization token. The redirect URL is the value of the AuthSub request next parameter. The token is a text string, up to 256 bytes.

http://www.yourwebapp.com/showcalendar.html?token=CKF50YzIHxCT85KMAg

The token returned is for a single use only; it lets you make only one request to the referenced Google service for that user. This limitation exists to secure authorization tokens specified in a URL. If you expect to make multiple calls to the Google service, you will want request a token that can be exchanged for a session token (in AuthSubRequest, set session to "true"). Then use the method AuthSubSessionToken.

AuthSubSessionToken

Call AuthSubSessionToken to exchange a single-use token for a long-lived session token. The single-use token is acquired by calling AuthSubRequest.

AuthSubSessionToken is a programmatic handler. Make an HTTP GET to the following URL: https://www.google.com/accounts/AuthSubSessionToken. Use an Authorization header with the following form:

Authorization: AuthSub token="token"

If the token is secure, it must be accompanied by a digital signature. See Signing requests for instructions and examples.

Parameter Description
token (required) The authorization token received from Google in response to an AuthSubRequest call.

Sample request

This example shows a request for a non-secure session token.

GET /accounts/AuthSubSessionToken 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

AuthSubSessionToken response

If the request for a session token is successful, Google responds with an HTTP 200 message with a set of key-value pairs in a "key=value" format. These values contain a session token and an expiration date. You can ignore the expiration date, which is not currently used; session tokens effectively do not expire.

Sample responses

This example illustrates an AuthSub token returned in the response header.

Token=DQAA...7DCTN
Expiration=20061004T123456Z

AuthSubRevokeToken

Call AuthSubRevokeToken to revoke a valid session token. Session tokens have no expiration date and remain valid unless revoked.

AuthSubRevokeToken is a programmatic handler. To revoke a session token, make an HTTP GET to the following URL: https://www.google.com/accounts/AuthSubRevokeToken. Use an Authorization header with the following form:

Authorization: AuthSub token="token"

If the token is secure, it must be accompanied by a digital signature. See Signing requests for instructions and examples.

Parameter Description
token (required) The session token, received in response to an AuthSubSessionToken request, to be revoked.

Sample request

This example shows a revocation request for a non-secure session token.

GET /accounts/AuthSubRevokeToken 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

AuthSubRevokeToken response

If the request for session token revocation is successful, Google responds with an HTTP 200 message.

AuthSubTokenInfo

Call AuthSubTokenInfo to test whether a given session token is valid. This method validates the token in the same way that a Google service would; application developers can use this method to verify that their application is getting valid tokens and handling them appropriately without making a call to the real Google service. It can also be used to get information about the token, including next URL, scope, and secure status, as specified in the original token request.

This method can be used for both single-use and session tokens. Keep in mind, however, that if it is called with a single-use token, the call is treated as a valid use. Consequently, the AuthSubTokenInfo response indicates the token is valid, but the token is rendered invalid from that point on.

AuthSubTokenInfo is a programmatic handler. Make an HTTP GET to the following URL: https://www.google.com/accounts/AuthSubTokenInfo. Use an Authorization header with the following form:

Authorization: AuthSub token="token"

If the token is secure, it must be accompanied by a digital signature. See Signing requests for instructions and examples.

Parameter Description
token (required) The authorization token received from Google in response to an AuthSubRequest call.

Sample request

This example shows a request for information on a non-secure token.

GET /accounts/AuthSubTokenInfo 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

AuthSubTokenInfo response

If the request is successful, Google responds with an HTTP 200 message with a set of key-value pairs in a "key=value" format. These values identify the target URL, scope, and secure status values, which were specified in the original token request. The target URL is simply the hostname gleaned from the next URL value.

Sample responses

This example illustrates a response containing a session authorization token.

Target=http://www.yourwebapp.com
Scope=http://www.google.com/calendar/feeds/
Secure=true

Special topics

This section covers some special topics related to Google Accounts authorization.

Signing AuthSub requests

All requests to Google services using a secure authorization token must be signed. This includes calls to AuthSubSessionToken, AuthSubRevokeToken, AuthSubTokenInfo, and all requests made to Google services. This section describes how to include a signature in a request.

Secure tokens are issued only to web sites or applications that have registered with Google. Part of the registration process includes providing a certificate to Google. To sign requests, the web application generates a signature from the private key corresponding to the certificate. Google supports the RSA signature algorithm, and may support additional signature algorithms in the future. When a signed request is received, the Google service verifies the signature before granting access. Requests using a secure token are denied if they are not signed.

Note: Some Google services respond to a request with a redirect. In this case, the redirected request must also be signed.

A signature is added to the "Authorization" header of the request, along with the authorization token. The header should take the form:

Authorization: AuthSub token="token" sigalg="sigalg" data="data" sig="sig"
Parameter Description
token (required) The authorization token received from Google in response to an AuthSubRequest call.
sigalg (required if token is secure) Signature algorithm. The only legal value for this parameter is "rsa-sha1", referring to SHA-1 with RSA using PKCS#1 padding.  In the future, more signature algorithms may be supported.
data (required if token is secure) The request metadata to be signed. The value of this parameter is a string with the following format:
 
data = http-method SP http-request-URL SP timestamp SP nonce
 
http-method: the HTTP method being invoked
SP: a single ASCII space character
http-request-URL: the full HTTP URL being requested
timestamp: an integer representing the time the request was sent, expressed in number of seconds after January 1, 1970 00:00:00 GMT
nonce: a random 64-bit, unsigned number encoded as an ASCII string in decimal

A timestamp/nonce combination should never be used more than once.
sig (required if token is secure) The signature for the secure token. This value must be a signature made by the private key corresponding to the certificate provided during registration. It must be encoded in BASE64, and must use the algorithm specified in the sigalg parameter.

Sample request:

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
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
Authorization: AuthSub token="token" data="GET https://www.google.com/accounts/AuthSubSessionToken 1148503696 15948652339726849410" sig="MCwCFrV93K4agg==" sigalg="rsa-sha1"
    

Note: The Authorization line must be on a single line.

Single sign-on

If your web application supports users with multiple Google services accessed through Google Accounts, you may be looking to get a single authorization token good for all of the user's Google services. This is called "single sign-on". Google now supports OpenID, an open-source standard that enables third-party sites to let their users sign in with Google user accounts. With OpenID (and OpenID+OAuth) users can sign in once using their Google account and get access to the third-party site as well as their Google services.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.