Set up Single Sign-On (SSO) for Google Apps accounts

In Single Sign-On (SSO)-enabled domains without network masks, super administrators must sign in with their Google Apps username and password, and users who aren't super administrators are redirected to the SSO sign-in page.

SSO is available for Google Apps for Work, Education, and Government. It enables users to access all of their Google Apps—including administrators signing in to the Admin console—by signing in one time for all services. If a user tries to sign in to the Admin console or another Google service when SSO is set up, they are redirected to the SSO sign-in page.

We provide a Security Assertion Markup Language (SAML)-based SSO API that you can use to integrate into your Lightweight Directory Access Protocol (LDAP), or other SSO system. LDAP is a networking protocol for querying and modifying directory services running over TCP/IP.

To use SSO, you need to generate a set of public and private keys and an X.509 certificate that contains the public key. The public keys and certificates must be generated with either the RSA or DSA algorithm and registered with Google. To register, you upload the key and certificate via your Google Admin console.

Set up SSO and upload the key and verification certificate
  1. Sign in to the Google Admin console.
  2. Click Security > Set up single sign-on (SSO). Where is it?
  3. Check the Setup SSO with third party identity provider box.
  4. Enter the appropriate URLs to set up the third-party Identity Provider (IdP).
  5. Upload your verification certificate.

    The certificate file must contain the public key so that Google can verify sign-in requests.

  6. Optionally, check the Use a domain-specific issuer box to enable a domain-specific issuer. If you enable this feature, Google sends an issuer specific to your domain, google.com/a/your_domain.com, where your_domain.com is replaced with your actual domain name.

    If you don't check the box to enable a domain-specific issuer when you set up SSO, Google sends the standard issuer, google.com, in the SAML request.

  7. Click Save Changes.

All URLs must use HTTPS, for example https://sso.domain.com.

For more information, see SAML SSO Service for Google Apps.

How do I generate keys and certificates for Google Apps SSO?

The way you generate keys and certificates often depends on your development platform and programming-language preference. To create public and private key pairs, you can use OpenSSL, the Certificate Creation tool and the Pvk2pfx tool in .NET, Keytool in Java, and Java Cryptography Architecture. For details, see Generating Keys and Certificates for Google Apps SSO.

How does the verification certificate work?

The certificate file must be an X.509-formatted certificate with an embedded public key. The public key must be generated with the DSA or RSA algorithms. This key is used to verify the SAML response you send to Google—that is, did the SSO assertion really come from you? It also makes sure the SSO assertion wasn't modified during transmission.

It is important to match the embedded public key in the X.509 certificate with the private key you use to sign the SAML response.

While we don't currently support a best practice for administrators without existing certificates, X509 certificates can be generated using the openssl command. For details, see Generating Keys and Certificates for Google Apps SSO.

How does the issuer—the entity ID element in the SAML request—work?

The issuer is included in the SAML request to the IdP (Identity Provider). You can choose whether to include a standard or domain specific issuer. When multiple domains are using SSO with the same IdP aggregator, a specific issuer can be parsed by the IdP aggregator to identify the correct domain name for the SAML request. If you don't check the box to enable a domain specific issuer, Google will send the standard issuer, google.com, in the SAML request. If you check the box to enable this feature, Google will send an issuer specific to your domain, google.com/a/your_domain.com, where your_domain.com is replaced with your actual domain name.

How do network masks work?

Network masks are IP addresses that are represented using Classless Inter-Domain Routing (CIDR) notation. The CIDR specifies how many bits of the IP address are included. Google uses network masks to determine which IPs or ranges of IPs to present with the SSO service. In domains without a network mask, you must add users who are not super administrators to the Identity Provider (IdP).

It is important for each network mask to use the correct format. In the following IPv6 example, the slash (/) and the number after it represent the CIDR. The last 96 bits are not taken into consideration, and all of the IPs in that network range are affected.

  • 2001:db8::/32

In this IPv4 example, the last 8 bits (the zero) are not be taken into consideration, and all of the IPs that were in the range of 64.233.187.0–64.233.187.255 would be affected.

  • 64.233.187.0/24

Note:

When network masks are enabled, all users and super admins are not redirected to their SSO from the Google sign-in page (accounts.google.com).

How does enabling SSO affect how users sign in?

The sign-in page for the Admin console is admin.google.com, which redirects to accounts.google.com, while the sign-in page for an individual Google service is service.google.com/a/your_domain.com. When you configure SSO for your domain, the behavior of these pages depends on whether the user signing in has super administrator privileges, and whether the domain has a network mask.

In SSO-enabled domains without a network mask:

  • When super administrators try to sign in to accounts.google.com, they are prompted for their full Google Apps email address (including username and domain) and password and are redirected to the Admin console after they sign in. Google does not redirect them to the SSO server.
  • When users without super administrator privileges try to sign at accounts.google.com, they are redirected to the SSO sign-in page.
  • When users without super administrator privileges, such as delegated administrators, try to sign in to admin.google.com, Google redirects them to the SSO server after they sign in with their Google Apps account details.
  • When users (with or without super administrator privileges) try to sign in to service.google.com/a/your_domain.com, Google redirects them to the SSO sign-in page.
  • All unauthenticated service requests via service.google.com/a/your_domain.com will be redirected to the SSO sign-in page.
    • Direct connections to accounts.google.com will be prompted for a username.
      If the user is a super administrator, they are prompted for a Google password
      If the user is not a super administrator, they are redirected to the SSO sign-in page.

In SSO-enabled domains with a network mask:

  • When users (with or without super administrator privileges) try to sign in to accounts.google.com, they are prompted for their full Google email address (including username and domain) and password, and takes them directly to the Admin console after they sign in. Google does not redirect them to the SSO server, regardless of the network mask.
  • When users (with or without super administrator privileges) within the network mask try to sign in to service.google.com/a/your_domain.com, they are redirected to the SSO sign-in page.
  • When users (with or without super administrator privileges) outside of the network mask try to sign in to service.google.com/a/your_domain.com, Google does not redirect them to the SSO sign-in page.
  • The originating IP of all unauthenticated service requests is checked when accessing via service.google.com/a/your_domain.com.
    • If the originating IP falls in a network mask (CIDR range), the user is redirected to the SSO sign-in.
    • If the originating IP does not fall within a network mask, the user is prompted for a username and then for a Google password.
    • Direct connections to accounts.google.com will be prompted for a username and then for a Google password.
How does the password change URL affect password changes?

If you specify a URL in the Change password URL option, all users, other than super administrators, who try to change their password at https://myaccount.google.com/ will be directed to the URL you specify. This setting applies even if you do not enable SSO. Also, network masks do not apply.

How does SSO impact super administrators?
  • SSO does not impact super administrators who try to sign in to an SSO-enabled domain through admin.google.com.
    After enabling SSO for a domain, instead of prompting for username and password, entering the email address of a super administrator will redirect to the sign-in page specified within the admin console.
  • When super administrators sign in to the Google Drive synchronization client, they bypass SSO.
  • When super administrators try to sign in to an SSO-enabled domain (with or without a network mask) via admin.google.com, they must enter their full Google administrator account email address and associated Google password (not their SSO username and password), and click Sign in to directly access the Admin console. Google does not redirect them to the SSO sign-in page. This applies to sign-in attempts from browsers, mobile apps (such as the iOS Drive and Gmail apps), the Android account activation flow, and so forth.
  • When super administrators try to sign in to another Google service at service.google.com/a/your_domain.com, Google redirects them to the SSO sign-in page only if they're signing in from within their domain's network mask. If they're outside of their domain's network mask, or if their domain doesn't have a network mask, Google prompts them for their Google username and password.
  • Clients such as Gmail for iOS, Drive for iOS, Chrome Browser Sync, Android setup, etc. use Google authentication. If you try to sign in with any of these clients, you are prompted for your full Google Apps account email address (including username and domain) and you go directly to the application after you sign in. Google does not redirect you to the SSO sign-in page, regardless of the network mask.
How do I set up SSO on Chrome devices? I have a question that is not covered above.

To resolve common issues, see Troubleshooting Single Sign-On. There are also a number of commercial products and system integrators that provide SSO products and professional services. Search the Google Apps Marketplace for Google for Work partners and other third parties that provide SSO assistance.