Single sign-on

You can configure your Cloud Identity or Google Workspace account to use single sign-on (SSO). When you enable SSO, users aren't prompted to enter a password when they try to access Google services. Instead, they are redirected to an external identity provider (IdP) to authenticate.

Using SSO can provide several advantages:

  • You enable a better experience for users because they can use their existing credentials to authenticate and don't have to enter credentials as often.
  • You ensure that your existing IdP remains the system of record for authenticating users.
  • You don't have to synchronize passwords to Cloud Identity or Google Workspace.

To use SSO, a user must have a user account in Cloud Identity or Google Workspace and a corresponding identity in the external IdP. SSO is therefore commonly used in combination with an external authoritative source that automatically provisions users to Cloud Identity or Google Workspace.

Single sign-on process

Cloud Identity and Google Workspace support Security Assertion Markup Language (SAML) 2.0 for single sign-on. SAML is an open standard for exchanging authentication and authorization data between a SAML IdP and SAML service providers. When you use SSO for Cloud Identity or Google Workspace, your external IdP is the SAML IdP and Google is the SAML service provider.

Google implements SAML 2.0 HTTP Redirect binding. This binding specifies how authentication information is exchanged between the SAML IdP and SAML service provider by using a number of HTTP redirects. The following diagram illustrates an example of how this process works when you use SSO to access the Google Cloud Console.

Using SSO to access the Google Cloud Console.

  1. You point your browser to the Cloud Console (or any other Google resource that requires authentication).
  2. Because you are not yet authenticated, the Cloud Console redirects your browser to Google Sign-In.
  3. Google Sign-In returns a sign-in page, prompting you to enter your email address.
  4. You enter your email address and submit the form.
  5. Google Sign-in looks up the Cloud Identity or Google Workspace account that is associated with your email address.
  6. Because the associated Cloud Identity or Google Workspace account has single sign-on enabled, Google Sign-In redirects the browser to the URL of the configured external IdP. Before issuing the redirect, it adds two parameters to the URL, RelayState and SAMLRequest.

    • RelayState contains an identifier that the external IdP is expected to pass back later.
    • SAMLRequest contains the SAML authentication request, an XML document that has been deflated, base64-encoded, and URL-encoded. In decoded form, the SAML authentication request looks similar to the following:

      <samlp:AuthnRequest
              ProviderName="google.com"
              IsPassive="false"
              AssertionConsumerServiceURL="https://www.google.com/a/example.com/acs"
              ...>
        <saml:Issuer xmlns:saml="...">google.com</saml:Issuer>
        <samlp:NameIDPolicy
              AllowCreate="true"
              Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"/>
      </samlp:AuthnRequest>
      

    This example request instructs the external IdP to authenticate the user, create a SAML assertion for the audience google.com, and post it to the assertion consumer service (ACS) at https://www.google.com/a/example.com/acs.

    The domain that is embedded in the ACS URL (example.com) corresponds to the primary domain of your Google Workspace or Cloud Identity account.

    If you use the domain-specific issuer feature when you configure SSO, the issuer is google.com/a/DOMAIN instead of google.com, where DOMAIN is the primary domain of your Cloud Identity or Google Workspace account.

    The steps taken by the external IdP to perform the authentication depend on the IdP and its configuration—for example, it might display a login dialog, or it might prompt for MFA or a fingerprint. When these steps have been completed successfully, the SAML exchange continues:

    SAML exchange using SSO.

  7. The external IdP returns a specially crafted HTML page that causes your browser to immediately send an HTTP POST request to the ACS URL. This request contains two parameters:

    • RelayState, which contains the value originally passed to the IdP in the SAML authentication request.
    • SAMLResponse, which contains the base64-encoded SAML assertion. The SAML assertion is an XML document that states that the IdP has successfully authenticated the user. In decoded form, the SAML assertion looks similar to the following:

      <samlp:Response ...>
        ...
        <Assertion x...>
          <Issuer>https://idp.example.org/</Issuer>
          <Signature ...>
            ...
          </Signature>
          <Subject>
            <NameID Format="...:nameid-format:emailAddress">bob@example.org</NameID>
            ...
          </Subject>
          <Conditions NotBefore="..." NotOnOrAfter="...">
            <AudienceRestriction>
              <Audience>google.com</Audience>
            </AudienceRestriction>
          </Conditions>
          <AttributeStatement>
            ...
          </AttributeStatement>
          <AuthnStatement AuthnInstant="..." ...>
            <AuthnContext>
              <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
            </AuthnContext>
          </AuthnStatement>
        </Assertion>
      </samlp:Response>
      

    This example assertion has been issued for the audience google.com (matching the issuer of the SAML authentication request) and states that the IdP https://idp.example.org/ has authenticated the user bob@example.org.

    The SAML assertion also contains a digital signature. The IdP creates this signature by using the private key of a signing certificate. The private key is known only to the IdP. The corresponding public key is part of the SSO configuration in Cloud Identity or Google Workspace and shared with Google Sign-In.

    The SAML assertion also contains a digital signature that enables the SAML service provider to verify the assertion's authenticity.

  8. The browser posts the SAML assertion to the Google ACS endpoint.

  9. The ACS endpoint verifies the digital signature of the SAML assertion. This check is done to ensure that the assertion originates from the trusted external IdP and has not been tampered with. Assuming the signature is valid, the ACS endpoint then analyzes the contents of the assertion, which includes verifying its audience information and reading the NameID attribute.

  10. The ACS endpoint looks up your user account by matching the NameID of the SAML assertion to the primary email address of the user. The endpoint then starts a session.

  11. Based on the information encoded in the RelayState parameter, the endpoint determines the URL of the resource that you originally intended to access, and you are redirected to the Cloud Console.

IdP-initiated sign-in

The process outlined in the previous section is sometimes referred to as service provider–initiated sign-on because the process starts at the service provider, which in the preceding example is the Cloud Console.

SAML also defines an alternative flow called IdP-initiated sign-on, which starts at the IdP. Google currently does not support this flow, but you can achieve similar results by using the following URL to initiate an service provider–initiated sign-on:

https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://console.cloud.google.com/

In this example, DOMAIN is the primary domain of your Cloud Identity or Google Workspace account.

Multi-factor authentication

To protect user accounts from unauthorized access, you can require users to provide a second factor during authentication. There are two ways to implement multi-factor authentication when using single sign-on:

  1. If your external IdP supports multi-factor authentication, you can have it perform the multi-factor authentication as part of the SAML-based sign-on process. No additional configuration is required in Cloud Identity or Google Workspace in this case.
  2. If your IdP does not support multi-factor authentication, you can configure your Cloud Identity or Google Workspace account to perform two-step verification immediately after a user has authenticated with the external IdP.

Networking

In SAML 2.0 HTTP Redirect binding, the IdP and service provider do not communicate directly. Instead, all communication is relayed through the user's browser, as shown in the following diagram:

Communication being relayed through the user's browser.

Given this architecture, it is not necessary for the IdP to be exposed over the internet, or to even have internet access, as long as users are able to access it from your corporate network.

Configuration of the external IdP

For SSO to work, the external IdP has to be configured to accept SAML authentication requests from Google Sign-In and to issue SAML assertions that are compatible with Google Sign-In. The following table summarizes the settings that typically have to be configured in an external IdP to help ensure compatibility.

Configuration Required setting Remarks
Attributes (or claims) NameID must contain the primary email address of a user in the Google Workspace or Cloud Identity account. Any additional attributes are ignored.
NameID format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Entity ID If the domain-specific issuer feature is enabled:

google.com/a/DOMAIN


If the domain-specific issuer feature is disabled (default):

google.com
If you want to set up SSO for multiple Google Workspace or Cloud Identity accounts so that a different entity ID is used for each account, in the Google Admin Console, enable the domain-specific issuer feature. Otherwise, keep the default setting.
ACS URL pattern (or Redirect URL) https://www.google.com/a/*
Request signing Off SAML authentication requests issued by Google Sign-In are never signed.
Assertion signing On SAML assertions must be signed to enable Google Sign-In to verify their authenticity.

When you set up SSO in the Admin Console, you must upload the public key of the token signing key-pair.
Assertion encryption Off
Signing algorithm RSA-SHA256 (sometimes abbreviated as RS256)

What's next