Duet AI is now Gemini for Google Workspace. Learn more

Technical overview of SAML-based SSO

With single sign-on (SSO), users can access many applications without having to enter their username and password for each application. Security Assertion Markup Language (SAML) is an XML standard that enables secure web domains to exchange user authentication and authorization data. 

The roles of service providers and identity providers

Google offers a SAML-based SSO service that allows partner companies to authorize and authenticate hosted users who are trying to access secure content. Google acts as the online service provider and provides services, such as Google Calendar and Gmail. Google partners act as online identity providers and control usernames, passwords and other information used to identify, authenticate, and authorize users for web applications that Google hosts. 

Many open source and commercial identity providers can help you implement SSO with Google.

Desktop clients still require logins

It’s important to note that the SSO solution applies only to web applications. You can enable your users to access Google services with desktop clients. For example, to provide POP access to Gmail using Outlook, you need to provide your users with usable passwords and synchronize those passwords with your internal user database using the Admin SDK's Directory API. When synchronizing your passwords, you should understand how users are authenticated using the admin control panel login URL.

Understanding partner-operated SAML-based SSO 

Figure 1 illustrates the process by which a user signs in to a Google application, such as Gmail, through a SAML-based SSO service that is partner operated. The numbered list that follows the image details each step.

Important: 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: This shows the process of signing in to Google using a SAML-based SSO service. 

This image illustrates the following steps.

  1. The user attempts to reach a hosted Google application, such as Gmail, Google Calendar, or another Google service.
  2. Google generates a SAML authentication request, which 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 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 browser redirects to the SSO URL.
  5. 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). 
  6. The partner then authenticates the user. Partners can authenticate users by either asking for valid login credentials or by checking for valid session cookies.
  7. The partner generates a SAML response that contains the authenticated user's username. In accordance with the SAML v2.0 specification, this response is digitally signed with the partner's public and private DSA/RSA keys.
  8. 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 submits the form to Google.
  9. The browser sends a response to the ACS URL. 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. 
  10. The user is signed in to the Google app.

Related topic

SAML v2.0 specifications

Was this helpful?

How can we improve it?
Clear search
Close search
Google apps
Main menu