The specification on this page is provided under the following Patent License.
Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
English ▼
| Sign in
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.
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.
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.
Authorization with AuthSub involves a sequence of interactions between three entities: the web application, Google services, and the user. This diagram illustrates the sequence:
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 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.
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.
Incorporating AuthSub into your web application requires these tasks:
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.)
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.
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.
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.
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.
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 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.
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:
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
If Google accepts the request:
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.
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.
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.
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. |
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: https://www.google.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive
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.
This example illustrates an AuthSub token returned in the response header.
Token=DQAA...7DCTN Expiration=20061004T123456Z
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. |
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
If the request for session token revocation is successful, Google responds with an HTTP 200 message.
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. |
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: https://www.google.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive
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.
This example illustrates a response containing a session authorization token.
Target=http://www.yourwebapp.com Scope=http://www.google.com/calendar/feeds/ Secure=true
This section covers some special topics related to Google Accounts authorization.
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 noncehttp-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: https://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.
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.