Troubleshooting Single Sign-On (SSO)

This error typically indicates that you are trying to use Single Sign On with a Standard (Free) Edition of Google Apps, which is not currently supported. If you are certain that you are using Google Apps for Work, Education, or ISPs, check the configuration in your Identity Provider to ensure that you have entered your Apps domain name correctly.

This error indicates that you have not set up Single Sign On correctly in your Apps Control Panel. Please review the following steps to correct the situation:

1. In your Apps Control Panel, in Security > Set up single sign-on, click the checkbox to Enable Single Sign-on.
2. Provide URLs for your organization's sign-in page, sign-out page, and change password page in the corresponding fields.
3. In the Verification certificate field, choose and upload a valid verification certificate file.
4. Click Save changes, wait a few minutes for your changes to take effect, and test your integration again.

This error message indicates that your Identity Provider is not providing Google with a valid SAML response of some kind. This problem is almost certainly due to a configuration issue in the Identity Provider.

• Check your Identity Provider logs and make sure that there is nothing preventing it from correctly returning a SAML Response.
• Ensure that your Identity Provider is not sending Google Apps an encrypted SAML Response. Google Apps only accepts SAML Responses that are unencrypted. In particular, please note that Microsoft's Active Directory Federation Services 2.0 often sends encrypted SAML Responses in default configurations.

The SAML 2.0 specification requires that Identity Providers retrieve and send back a RelayState URL parameter from Resource Providers (such as Google Apps). Google Apps provides this value to the Identity Provider in the SAML Request, and the exact contents can differ in every login. For authentication to complete successfully, the exact RelayState must be returned in the SAML Response. According to the SAML standard specification, your Identity Provider should not modify the RelayState during the login flow.

• Diagnose this issue further by capturing HTTP headers during a login attempt. Extract the RelayState from the HTTP headers with both the SAML Request and Response, and make sure that the RelayState values in the Request and Response match.
• Most commercially-available or open-source SSO Identity Providers transmit the RelayState seamlessly by default. For optimum security and reliability, we recommend that you use one of these existing solutions and cannot offer support for your own custom SSO software.

This error indicates that the destination or audience elements in the SAML assertion contained invalid information or were empty. Both elements must be included in the SAML assertion. Check the following table for descriptions and examples for each element.

For details of all the required elements, please review the topic, "What are the required elements for SAML 2.0 SSO assertions?," under Set up Single Sign-On for Google Apps accounts.

This error usually indicates that the SAML Response from your Identity Provider lacks a readable Recipient value (or that the Recipient value is incorrect). The Recipient value is an important component of the SAML Response, as detailed in our FAQ.

1. Diagnose this issue further by capturing HTTP headers during a login attempt.
2. Extract the SAML Request and Response from the HTTP headers.
3. Ensure that the Recipient value in the SAML Response exists and that it matches the value in the SAML Request.

Note: this error message may also appear as "This service cannot be accessed because your login request contained invalid recipient information. Please log in and try again."

This error indicates a problem with the certificates that you are using to sign the authentication flow. Specifically, this usually means that the private key used to sign the SAML Response does not match the public key certificate that Google Apps has on file.

This error might also mean that your SAML Response does not contain a viable Google Accounts username. Google Apps parses the SAML Response for a XML element called a NameID, and expects that this element either contains a Google Apps username or a full Google Apps email address.

• In your Apps Control Panel, access your SSO setup page by navigating to Advanced Tools > Set up single sign-on. Ensure that you are using a valid certificate and re-upload it in the SSO setup form.
• If you are using a full email address in your NameID element (you must be if you are using SSO with a multidomain Apps environment), ensure that the Format attribute of the NameID element specifies that a full email address is to be used, as in the following example: Format="urn:oasis:names:tc:SAML:2.0:nameid-format:email"
• Ensure that you are not populating the NameID element with something other than a valid username or email address, such as a database id field. To be certain, extract the SAML Response you sending to Google Apps, and check the value of the NameID element to ensure that it is correct.
• If your Identity Provider is encrypting your SAML Assertion, disable this encrypting and ensure that the Assertion is sent to Google in an unencrypted format so that it is readable by Apps.

For security reasons, the SSO login flow must complete within a certain timeframe, or authentication will fail. If the clock on your Identity Provider is incorrect, most or all login attempts will appear to be out of the acceptable timeframe, and authentication will fail with the above error message.

• Check the clock on your Identity Provider's server. This error is almost always caused by the Identity Provider's clock being incorrect, which adds incorrect timestamps to the SAML Response.
• Re-sync the Identity Provider server clock with a reliable internet time server. When this issue suddenly occurs in a production environment, it is typically because the last time sync failed, causing the server time to become inaccurate. Repeating the time sync (possibly with a more reliable time server) will quickly remedy this issue.
• This issue can also occur if you are re-sending SAML from a previous login attempt. Examining your SAML Request and Response (obtained from HTTP header logs captured during a login attempt) can help you debug this further.

For security reasons, the SSO login flow must complete within a certain timeframe, or authentication will fail. If the clock on your Identity Provider is incorrect, most or all login attempts will appear to be out of the acceptable timeframe, and authentication will fail with the above error message.

• Check the clock on your Identity Provider's server. This error is almost always caused by the Identity Provider's clock being incorrect, which adds incorrect timestamps to the SAML Response.
• Re-sync the Identity Provider server clock with a reliable internet time server. When this issue suddenly occurs in a production environment, it is typically because the last time sync failed, causing the server time to become inaccurate. Repeating the time sync (possibly with a more reliable time server) will quickly remedy this issue.