Single Sign-On

Note: There's a new Google Apps Marketplace experience! Beginning November 19, 2013, new listings may only be created using the new version: existing developers may need to create a new Chrome Web Store account to publish new listings. Refer to the new documentation for more information.

OpenID Single Sign-On (SSO) must be used in all installable Apps Marketplace applications to provide a seamless login experience. For in-house apps developed with the Google Apps extensions console, implementing Single Sign-On is a strongly recommended best practice. The end user should not be required to enter a username and password when invoking an application from within Google Apps.

This document gives an overview of SSO for developers who are creating applications for the Apps Marketplace or for their own domain.

Google I/O 2010 Video: OpenID Single Sign-On and OAuth Data Access

View the slides from this presentation

Why it's important

The use of Single Sign-On increases both convenience and security:

  • Applications that implement SSO feel like they are part of the Google Apps suite, leading to a better user experience.
  • SSO removes the user's burden of maintaining and remembering another login and password for a new web application.
  • The user's ID and password are stored at a single secure location, the OpenID provider. This is more secure than having the user create a separate ID and password for each application or, even worse, re-use a password in multiple accounts.

What it looks like

From the end user's point of view, SSO is actually invisible: the user is logged in to Google Apps, going about their daily tasks, and then clicks a link or takes some other action that invokes an application. The application appears, and the user can immediately begin working with it. The SSO operation occurred behind the scenes, in between the invocation and display of the application. If the user notices anything, it will be the absence of an intermediate login step.

Caution: Every Marketplace application should present an invocation flow that is free of an intermediate login step. The end user should never be asked to provide an ID and password. Applications that do not follow this flow will not be approved for listing in the Marketplace.

  1. The user invokes an application, perhaps by clicking a link in the Universal Navigation "more" menu.
  2. The user does not take any further action. A user ID and password are not required.
  3. The application appears.

How it works

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 this 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.

If you choose to accept OpenID logins directly from your web application, consider checking Google's user experience guidelines for federated login. Account Chooser offers a reference implementation using the Google Identity Toolkit.

Note that all Google consumer accounts (like @gmail.com accounts) can be used to sign in with OpenID, using the numerous OpenID libraries supporting the standard discovery process. When a user signs in with OpenID, you will have access to both their email address as well as a unique identifier.

NOTE: your Google Apps domain will need to be verified before OpenID will function properly.

Typical SSO flow

The typical SSO flow is as follows:

  • User clicks application link in Google's universal navigation
  • Navigation link includes an auto-populated ${DOMAIN_NAME} parameter in the URL, which references the user's domain
  • When arriving at the application, the domain parameter is used to seed OpenID discovery
  • Since the application is installable, and includes the OpenID realm in the application manifest, the application is whitelisted for OpenID, and the verification step is skipped
  • The user is redirected to the application and is logged in

For example applications that implement this flow, check out the tutorials.

The importance of the OpenID realm

The OpenID realm declared in the application manifest must exactly match the OpenID realm passed in requests from your application. Trailing slashes, http vs. https, and any other differences are significant.

When your application performs single sign-on, users should not be prompted for authorization. If they are, whitelisting has failed, and the realm declared in the manifest does not match the one sent by your application. You should consider this a bug in your code and adjust the manifest or application code appropriately. The one exception to this is applications which do hybrid OpenID/OAuth — whitelisting does not currently work with this approach.

Note that if you grant authorization during single sign-on prior to having whitelisting configured properly, that authorization may be remembered. This can potentially mask issues in your application. Before releasing an application make sure to test it with a new user account (that has never granted OpenID authorization) or on a fresh domain. This will ensure that your application has declared the OpenID realm correctly.

Getting started

It is recommended that developers use an existing OpenID library rather than implement their own. Libraries supporting the OpenID Google Apps discovery extensions are available in a number of languages, and the libraries (or extensions) provide getting started instructions:

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

For example applications that implement OpenID SSO, check out the tutorials.