SAML Single Sign-On (SSO) Service for Google Apps

Security Assertion Markup Language (SAML) is an XML standard that allows secure web domains to exchange user authentication and authorization data. Using SAML, an online service provider can contact a separate online identity provider to authenticate users who are trying to access secure content.

Google Apps offers a SAML-based Single Sign-On (SSO) service that provides partner companies with full control over the authorization and authentication of hosted user accounts that can access web-based applications like Gmail or Google Calendar. Using the SAML model, Google acts as the service provider and provides services such as Gmail and Start Pages. Google partners act as identity providers and control usernames, passwords and other information used to identify, authenticate and authorize users for web applications that Google hosts. There are a number of existing open source and commercial identity provider solutions that can help you implement SSO with Google Apps.

It is important to note that the SSO solution only applies to web applications. If you want to enable your users to access Google services with desktop clients such as Outlook—for example, providing POP access to Gmail using Outlook—you will still need to provide your users with usable passwords and synchronize those passwords with your internal user database using the Admin SDK's Directory API. In addition when sychronizing your passwords, it is useful to understand how users are authenticated using the admin control panel login URL.

The Google Apps SSO service is based on the SAML v2.0 specifications. SAML v2.0 is supported by several widely known vendors.

Understanding SAML-based SSO for Google Apps

The following process explains how a user logs into a hosted Google application through a partner-operated, SAML-based SSO service.

Figure 1, shown below, illustrates the process by which a user logs in to a Google Apps application, such as Gmail, through a SAML-based SSO service. The numbered list that follows the image explains each step in more detail.

Note: Before this process takes place, the partner must provide Google with the URL for its SSO service as well as the public key that Google should use to verify SAML responses.

Figure 1: Logging in to Google Apps using SAML

This image illustrates the following steps.

1. The user attempts to reach a hosted Google application, such as Gmail, Start Pages, or another Google service.
2. Google generates a SAML authentication request. The SAML request is encoded and embedded into the URL for the partner's SSO service. The RelayState parameter containing the encoded URL of the Google application that the user is trying to reach is also embedded in the SSO URL. This RelayState parameter is meant to be an opaque identifier that is passed back without any modification or inspection.
3. Google sends a redirect to the user's browser. The redirect URL includes the encoded SAML authentication request that should be submitted to the partner's SSO service.
4. The partner decodes the SAML request and extracts the URL for both Google's ACS (Assertion Consumer Service) and the user's destination URL (RelayState parameter). The partner then authenticates the user. Partners could authenticate users by either asking for valid login credentials or by checking for valid session cookies.
5. The partner generates a SAML response that contains the authenticated user's username. In accordance with the SAML 2.0 specification, this response is digitally signed with the partner's public and private DSA/RSA keys.
6. The partner encodes the SAML response and the RelayState parameter and returns that information to the user's browser. The partner provides a mechanism so that the browser can forward that information to Google's ACS. For example, the partner could embed the SAML response and destination URL in a form and provide a button that the user can click to submit the form to Google. The partner could also include JavaScript on the page that automatically submits the form to Google.
7. Google's ACS verifies the SAML response using the partner's public key. If the response is successfully verified, ACS redirects the user to the destination URL.
8. The user has been redirected to the destination URL and is logged in to Google Apps.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Last updated August 19, 2013.