Frequently Asked Questions

Getting Started

Authentication | Provisioning API | Reporting API | Email Migration API | Single Sign-On (SSO) | Shared Contacts



• What is Google Apps?
• What can I do with the Google Apps APIs?
• How do I enable the Google Apps APIs?
• How do I install and use the .NET Client Library?
• Where can I find the Developer Guide?
• I have a different question/problem than what's covered here. Who should I contact?
• How do I submit a feature request for one of the Google Apps APIs?
• How do I contact Google Apps customer support?

Authentication

• Can we request more than one authentication token?
• What is the time to live of an authentication token?
• Will the most recent token request invalidate the previous unexpired token?
• I received a CAPTCHA error during authentication, what is a CAPTCHA?
• How do we handle a CAPTCHA challenge?
• Under what circumstances will Google's authentication system generate a CAPTCHA challenge?
• Why do I keep getting CAPTCHA errors even after I unlock the administrator account?
• How can I avoid CAPTCHA errors in my program?
• What is AuthSub?
• What is OAuth?
• Does SAML SSO work with AuthSub?

Provisioning API

• Can I enable POP3 for a user with the Provisioning API?
• Can I allow my newly created users to bypass the Google Apps Welcome/Terms of Service page through the Provisioning API?
• How can I rename a username?
• Why is the user count in the control panel incorrect?
• How do I synchronize LDAP or Active Directory with Google Apps?
• Can I encrypt passwords sent to the Provisioning API?
• Does the Java client library work with J2SDK 1.4.2?
• Does the PHP client library work with PHP 4?
• How can I monitor my request and response to and from Google?
• How can I reuse a deleted username?
• How do I edit the email contacts for a user?
• I need to create a lot of users in a short time. How can I speed up the Provisioning API?

Reporting API

• Why am I getting an HTTP 401 status code from the Reporting API?
• Why am I getting a "ReportNotFound(1045)" error message for today's reports?
• My domain has a lot of users. How can I download the large accounts report? It keeps timing out.

Email Migration API

• How can I migrate emails in character sets other than ISO-8859-1?
• Why am I getting an HTTP 503 error code?

Single Sign-On (SSO)

• What version of SAML does the SSO API supports?
• Can we use RSA instead of DSA for the single sign-on implementation?
• How can I generate the verification certificate required for SSO?
• If our domain implements SSO, can we still login to Google directly?
• Why can't I set a persistent cookie at Google using the SAML SSO solution?
• How can the non-persistent session cookie that identifies a user during a browser session be deleted (e.g. upon logout)?
• What does this error message mean: "This account cannot be accessed because the login credentials could not be verified"?
• Why isn't the Change password URL working?
• Why does the SAMLResponse HTML form work in Firefox but not in Internet Explorer?
• How can I allow users to view the partner start page without authenticating?
• Does SAML SSO work with POP3 or IMAP?
• Does SAML SSO work with the Gmail Atom feed?
• Does SAML SSO work with AuthSub?
• What is the Recipient attribute which is required in the SAML Response?
• What does this error message mean: "This service cannot be accessed because your login request contained no recipient information"?
• What does this error message mean: "This service cannot be accessed because your login request contained invalid recipient information"?
• How do I ensure my third-party identity provider specifies the right Recipient attribute?
• How do I add the Recipient attribute to my existing code based on the Java sample code?
• How do I add the Recipient attribute to my existing code based on the C# .NET sample code?
• How do I add the Recipient attribute to my existing code based on the PHP sample code?

Shared Contacts

• What is the difference between Contacts, Shared Contacts and Profiles?
• Where can I see my Domain Shared Contacts?

---

Getting Started

What is Google Apps?

Google Apps lets you offer private-labeled email, IM and calendar accounts to all of your users, so they can share ideas and work more effectively. These services are all unified by the Start Page—a unique, dynamic page where your users can preview their inboxes and calendars, browse content and links that you choose, search the web, and further customize the page to their liking. You can also design and publish web pages for your domain. Everything is hosted by Google so no hardware or software is required.

What can I do with the Google Apps APIs?

We currently offer two administrative APIs, one for user provisioning and one for single sign-on (SSO). The Provisioning API allows you to programmatically manage user accounts and synchronize your Google Apps user base with your own user management system. The SSO service allows you to integrate your own authentication system with Google Apps and securely log your users into the web based hosted Google applications.

Google Calendar data API, Google Gadgets API, Google Spreadsheets data API, and Google Talk XMPP are also available to allow you to customize Google Calendar, Start Page, Google Spreadsheets, and Google Talk Client, respectively.

How do I enable the Google Apps APIs?

The Premier and Education Editions have access to Google Apps Administrative APIs. Both APIs allow you to integrate with Google Apps using your existing account management system and/or website. To enable API access:

1. Log in to your control panel.
2. Click User accounts.
3. Click the Settings tab.
4. For Provisioning API: Check the box next to Enable provisioning API.
   For Single sign-on: Click Set up single sign-on (SSO), enter the appropriate URLs, and upload your verification certificate. Visit the SSO Reference for more instructions.
5. Click Save changes.

How do I install and use the .NET Client Library?

You can find more information in the Getting Started with the .NET Client Library article.

Where can I find the Developer Guide?

The Developer Guide can be found at http://code.google.com/apis/apps/overview.html.

I have a different question/problem than what's covered here. Who should I contact?

Please post your question in the Google Apps APIs Help Forum to get help from the Google Apps developer community. The Google Apps team regularly monitors and participates in this group.

How do I submit a feature request for one of the Google Apps APIs?

To submit a feature request, post it in the Google Apps APIs Help Forum.

How do I contact Google Apps customer support?

Instructions for contacting customer support are in the Google Apps control panel. Your Customer and Support PINs are also listed there.

---

Authentication

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.

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:

   accountType=HOSTED&Email=johndoe@yourdomain.com&Passwd=north23AZ&logintoken=DQAAAGgA...dkl1LK9&logincaptcha=randomized

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

   https://www.google.com/a/yourdomain.com/UnlockCaptcha

   Note: Please replace yourdomain.com with your domain name.

   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.

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.

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, please visit
http://code.google.com/apis/accounts/docs/AuthForWebApps.html.

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: http://code.google.com/apis/accounts/docs/OAuth.html

---

Provisioning API

Can I enable POP3 for a user with the Provisioning API?

Unfortunately we cannot enable POP3 until a user has agreed to the Terms of Service. This is why the Provisioning API does not have the option to enable POP3.

Can I allow my newly created users to bypass the Google Apps Welcome/Terms of Service page through the Provisioning API?

Unfortunately we cannot enable their account until a user has agreed to the Terms of Service. This is why the Provisioning API does not have the option to bypass the Terms of Service prompt.

How can I rename a username?

Renaming a username is now supported using the Provisioning API v2.0. See the Developer's Guide for more details.

Why is the user count in the control panel incorrect?

The user count in the control panel is calculated daily for Google Apps Partner and Education Edition domains. For Premier Edition domains, the user count can become inaccurate if users are created or deleted with a multi-threaded application.

How do I synchronize LDAP or Active Directory with Google Apps?

See the Google Apps LDAP sync project for an example of how to do this.

Can I encrypt passwords sent to the Provisioning API?

The Provisioning API accepts SHA-1 hashed passwords. See the documentation of hashFunctionName for more details.

Does the Java client library work with J2SDK 1.4.2?

No, the Java client library relies on language features from Java 1.5.

Does the PHP client library work with PHP 4?

No, the PHP client library is part of Zend Framework and requires features found in PHP 5.1.4 and later.

How can I monitor my request and response to and from Google?

There are a number of tools that helps you monitor your connection with Google. You can download tcpmon, an open-source utility to monitor TCP connection.

How can I reuse a deleted username?

After you delete an account, you must wait five days before reassigning the username of the deleted account to another account.

How do I edit the email contacts for a user?

Use the Contacts API.

I need to create a lot of users in a short time. How can I speed up the Provisioning API?

Creating a user can take several seconds. To increase the throughput, write a multi-threaded application to create users in parallel. Java, .NET, and Python support multi-threaded programming.

---

Email Migration API

How can I migrate emails in character sets other than ISO-8859-1?

Some character sets, e.g. ISO-2022-JP, are not compatible with XML. If this is the case, you may base64-encode the email. See the documentation on the rfc822 encoding attribute.

Why am I getting an HTTP 503 error code?

There is an unspecified rate limit on the number of messages per user per second. HTTP 503 indicates that the rate limit has been exceeded. To handle this, consider implementing an exponential backoff algorithm and an algorithm which interleaves small batches of emails from different users.

---

Reporting API

Why am I getting an HTTP 401 status code from the Reporting API?

Please double-check that you are submitting the SID token with the report request and not the LSID or Auth tokens provided by ClientLogin.

Why am I getting a "ReportNotFound(1045)" error message for today's reports?

Reports for today's date are not available until tomorrow at 12:00 Pacific time. See the Reporting API documentation for more details.

My domain has a lot of users. How can I download the large accounts report? It keeps timing out.

Try retrieving the gzip compressed report. See the documentation on compression.

If that does not work, try retrieving the report one page at a time. See the documentation on paging in the accounts report.

---

Single Sign-On

What version of SAML does the SSO API supports?

We currently support SAML v2.0. Visit http://www.oasis-open.org/specs/index.php#samlv2.0 to find details on the SAML v2.0 standard.

Can we use RSA instead of DSA for the single sign-on implementation?

Yes, you can choose to use RSA or DSA encryption algorithm. We accept both.

How can I generate the verification certificate required for SSO?

X509 certificates generation can be accomplished using the openssl command.

If our domain implements SSO, can we still login to Google directly?

With SSO implemented, domain end users will not be able to log in to Google directly. However, domain admins can still log in to the Google control panel (e.g http://www.google.com/a/yourdomain.com).

Why can't I set a persistent cookie at Google using the SAML SSO solution?

SAML does not specify a mechanism to set expiration times for sessions, and this is generally a good thing. If you could set authentication credentials for Google applications with different expiration parameters than for your non-Google properties, a mismatch in credentials could occur such that, on a shared computer, user "A" would be authenticated at Google, and user "B" could be authenticated at the Identity Provider's other properties simultaneously. To the extent that both Google-hosted and non-Google-hosted applications are viewed as a cohesive set of services, this would result in a loss of privacy and a poor user experience.

If you wish to set authentication credentials that last longer than the lifetime of the browser (the default time for Google authentication sessions), then you will need to implement a cookie on your SSO service that lasts for a longer period of time. You may then check that cookie when we send the user to you for authentication, and identify them securely, without needing to prompt for a username/password.

How can the non-persistent session cookie that identifies a user during a browser session be deleted (e.g. upon logout)?

After successful authentication via SAML, Google sets a session cookie to identify an user's session. When the user explicitly logs out (e.g. by clicking the logout button), this cookie needs to be destroyed. If your implementation involves persistent session management ("remember me on this computer" functionality), you may need to control how and when this cookie is destroyed. Upon logout, Google redirects to your logout servlet. In your logout servlet, you may present the user with some options that could determine whether the session cookie should be deleted or not.

What does this error message mean: "This account cannot be accessed because the login credentials could not be verified"?

This usually means that the private key used to sign the SAMLResponse does not match the public key certificate that Google Apps has on file. Please upload the certificate in the SSO Settings in control panel and retry.

Why isn't the Change password URL working?

Changes to the Change password URL in SSO Settings take about an hour to become effective.

Why does the SAMLResponse HTML form work in Firefox but not in Internet Explorer?

It may be due to Internet Explorer misinterpreting the RelayState. Internet Explorer interprets "&ltmpl" as "<mpl". To prevent this from happening, XML special characters should be escaped in the RelayState. Change { &, <, >, ', " } to { &amp;, &lt;, &gt;, &apos;, &quot; }.

How can I allow users to view the partner start page without authenticating?

See this topic in the discussion group for an example SAMLResponse.

Does SAML SSO work with POP3 or IMAP?

No, SAML only works with the Google Apps web applications.

Does SAML SSO work with the Gmail Atom feed?

No, the Gmail Atom feed uses HTTP basic authentication.

Does SAML SSO work with AuthSub?

Yes, SAML does work with AuthSub.

What is the Recipient attribute which is required in the SAML Response?

According to section 4.1.4.2 of the SAML 2.0 profiles specification, the Recipient attribute should be equal to the Assertion Consumer Service (ACS) URL. It is located here:

<samlp:Response ...>
  <saml:Assertion ...>
    <saml:Subject>
      <saml:NameID ...>user@domain.com</saml:NameID>
      <saml:SubjectConfirmation ...>
        <saml:SubjectConfirmationData Recipient="https://www.google.com/a/domain.com/acs" .../>
      </saml:SubjectConfirmation>
    </saml:Subject>
  </saml:Assertion>
</samlp:Response>

See the questions below for how you can add the Recipient to the SAML Response.

What does this error message mean: "This service cannot be accessed because your login request contained no recipient information"?

It means the SAML Response is missing a required Recipient attribute.

What does this error message mean: "This service cannot be accessed because your login request contained invalid recipient information"?

It means the Recipient attribute in the SAML Response does not match the Assertion Consumer Service (ACS) URL.

How do I ensure my third-party identity provider specifies the right Recipient attribute?

If your commercial or open-source identity provider supports SAML 2.0, it should already specify the correct Recipient attribute. If you are getting one of the error messages above, it means that the Recipient attribute is incorrect. If this is the case, contact the vendor or the maintainer of the software and send them the link to this page.

How do I add the Recipient attribute to my existing code based on the Java sample code?

In order to support the Recipient attribute, you will have to update the getRequestAttributes, createSamlResponse, doGet, and doPost methods in ProcessResponseServlet.java and get the latest SamlResponseTemplate.xml.

How do I add the Recipient attribute to my existing code based on the C# .NET sample code?

In order to support the Recipient attribute, you will have to update the CreateRawResponseXml method in SamlParser.cs and get the latest SamlResponse.xml.

How do I add the Recipient attribute to my existing code based on the PHP sample code?

In order to support the Recipient attribute, you will have to get the latest SamlResponseTemplate.xml.

---

Shared Contacts

What is the difference between Contacts, Shared Contacts and Profiles?

In Google Apps there are 3 different kind of contacts and each kind has a different API:

1. Contacts: The Contacts Data API allows client applications to view and update user's contacts, these contacts are unique to the user and not shared with anyone else. Your client application can use the Contacts Data API to create new contacts, edit or delete existing contacts, and query for contacts that match particular criteria. For more information visit: Google Contacts Data API

2. Profiles: The Profiles Data API allows client applications to retrieve and update profile information for users in a Google Apps domain, the profile information is shared with all users in the domain if contact sharing is enabled. Also, the profile information can only be modified by the domain administrators. Every user has a profile even if it is never used and thus a profile cannot be inserted or deleted. It is important to mention that profiles includes only users of the domain, it does not include nicknames or groups (email lists). For more information visit: Google Apps Profiles API

3. Shared Contacts: The Shared Contacts API allows client applications to create, retrieve, delete and update contacts that are shared to all users in a Google Apps domain, except for the domain's users (e.g. user@domain.com). Shared contacts are visible to all users of the domain if contact sharing is enabled. It is important to mention that shared contacts should be used to add contact information of the domain's nicknames and groups (email lists). For more information visit: Google Apps Shared Contacts API

Where can I see my Domain Shared Contacts?

Shared contacts are only visible in two places after 24 hours of their creation, in the domain Contact Manager when you *search* for a Shared Contact and in the Gmail compose emails fields by auto complete. The regular user Contact Manager within Gmail only shows normal user contacts.

---