Authentication FAQ


See also


What authentication and authorization choices are available with Google Apps APIs?

Check out the Auth getting started guide to learn about the authentication and authorization choices available to Google Apps APIs.

What is AuthSub?

AuthSub is an authentication proxy service that allows your web applications to get access to Google Apps services (such as Calendar, DocList, and Spreadsheets APIs) without having to handle the user's account login information directly.

With this method, users visiting your web applications are redirected to a Google server to authenticate to their Google Apps account. After approving your application to access a specific Google Apps service, the user is then redirected back to your application with a one-time-use token. This token can be exchanged for a session token that allows the application to make unlimited calls to the Google Apps service for that user.

To learn more about using AuthSub, see Authentication for Web Applications.

What is OAuth?

OAuth is a web application authentication mechanism similar to AuthSub, but it is a standard which several companies have adopted. For more information on OAuth, please visit OAuth 1.0 for Web Applications.

What is two-step verification?

Two-step verification adds an extra layer of security to your Google Apps account by requiring you to enter a verification code in addition to your username and password. For an API where there is no property for a verification code, use a two-step access code as your password. To learn more about two-step verification and how to generate an access code, see http://www.google.com/support/a/bin/answer.py?answer=175197.

OpenID-based SSO

What are the OpenID Google Apps discovery extensions?

To enable Google Apps users to login to third-party websites, Google has become an OpenID identity provider (IDP) via the OpenID Federated Login Service. With Federated Login enabled, Google Apps users can use OpenID to authenticate with third-party applications that are OpenID Relying Parties (RP).

For a high-level overview of Google's Federated Login Service, see the following article. It is important to note that the RP must use a slightly different discovery mechanism to support Google Apps accounts, which is covered in depth here. In short, during the OpenID discovery process, RPs must check both (using example.com as the example domain) https://www.google.com/accounts/o8/.well-known/host-meta?hd=example.com and http://example.com/.well-known/host-meta for discovery information, as the site owners may opt to have Google host this information, rather than host it themselves.

What libraries are available for supporting the OpenID Google Apps discovery extensions?

Libraries supporting the OpenID Google Apps discovery extensions are available in a number of languages:

Support for discovery extensions is also available when using MyOneLogin, Ping Connect, and RPX.

Auth Tokens

Can we request more than one authentication token?

Yes, you can request and have active more than one token at a time.

What is the time to live of an authentication token?

Authentication tokens expire after 24 hours. We recommend that you keep the token in memory rather than writing it to a file.

Will the most recent token request invalidate the previous unexpired token?

No, the most recent token request will not invalidate the previous unexpired tokens. You can have multiple valid tokens.

How do I get a ClientLogin authentication token when using an account enrolled in two-step verification?
For an API using ClientLogin authentication, use your two-step access code in the Passwd attribute when making a POST request to the ClientLogin resource. For information about how to generate a two-step access code, see Mobile, Desktop, and API. An example of the POST body is:



I received a CAPTCHA error during authentication, what is a CAPTCHA?

A CAPTCHA is a test to determine whether or not the user is human. It typically requires the user to type the letters of a distorted visual image. A CAPTCHA ensures that a real person is attempting login, and not a computer trying random strings (a "dictionary" attack).

How do we handle a CAPTCHA challenge?

There are 2 ways to handle a CAPTCHA challenge:

  1. Your application can display the CAPTCHA image and solicit an answer from the user. To display the CAPTCHA image, use the CaptchaUrl returned with the login failure response. Once the user provides an answer, your application should resend (POST) the login request, this time including the CAPTCHA token and the user's answers. Google will validate the user's answer before authorizing access to the account. So, when responding to a CAPTCHA, your POST body string will look like the following:


  2. Your application can direct the user to the Google hosted page:


    Once the user has successfully responded to the challenge, the Google server will trust the computer in use. The application can then resend the original login request to obtain the authentication token.

    Note: If your domain has not been transitioned to our new infrastructure for Google Apps, your application should instead direct users to https://www.google.com/a/yourdomain.com/UnlockCaptcha. Please replace yourdomain.com with your domain name.

Under what circumstances will Google's authentication system generate a CAPTCHA challenge?

First of all, you should not get a CAPTCHA if things are working normally. You may get a CAPTCHA if we suspect illegal intrusion such as after too many incorrect login attempts. A CAPTCHA ensures that a real person is attempting to log in, and not a computer trying random strings (a "dictionary" attack).

Why do I keep getting CAPTCHA errors even after I unlock the administrator account?

Please verify in your code that you are specifying your full administrator email address e.g. "admin@domain.com" instead of just "admin".

How can I avoid CAPTCHA errors in my program?

Too many authentication attempts (successful or failed) can cause a CAPTCHA error. Since the Auth token is valid for 24 hours, you can cache this token in memory and reuse it for all Provisioning API operations while the token is valid. If you have a multi-threaded application, you can share this token among threads.