Troubleshooting authentication errors can be challenging when you're using SSO embed for your Looker content. Depending on where your users are getting redirected to, there are a few different paths you can try to pinpoint any issues you might encounter. The tips below assume that you are generating your SSO embed URL using a script similar to those in Looker's SSO Examples Github repository, unless stated otherwise.

General things to try first

Before you begin embedding, make sure that your embed secret has been generated in the Admin panel and that your embedded content is functional in Production Mode, not just in Development Mode.

If you have admin permissions, sudo as the embed user to check that your content is functional. If you get the error Oops, we can't find that page, then the issue is most likely with permissions or content access and not related to an authentication issue. If the embed user isn't showing up in the Users page of the Looker Admin panel, then the user has not been created and the embed URL is failing. You can try troubleshooting the issue using some of the suggestions and resources listed in this article.

If your instance is self-hosted, make sure that the client server can reach the Looker server, and, if the data between the client and server is transmitted over the public Internet, make sure that SSL (HTTPS) is being used.

The rest of this article describes errors and other issues you may be encountering and steps for resolving them.

I'm getting redirected to either a login page or a "Single sign-on failure" page

If you're getting redirected to the login page or to a page that indicates a single sign-on failure, this typically indicates that the SSO embed authentication is not working properly.

First, generate a new SSO embed URL and test it in the Embed URI Validator under the Embed page of the Looker Admin panel. The Embed URI Validator can sometimes reveal valuable information as to why you encounter an error. Below are some of the more common causes of these errors.

Is the Embed URI Validator appearing as expected?

If you are on the Embed page of the Looker Admin panel and the Embed URI Validator does not appear on the page, this suggests that SSO embedding has not been enabled yet. You will need to enable SSO embedding.

I'm receiving the 'signature param' failed to authenticate error

If you see the 'signature' param failed to authenticate error, the signature generated by your script is not working as expected.

Do the SSO secrets match?

The embed secret in your Looker instance should be identical to the SSO secret in your SSO generation script. If you are unsure if this is true, select Reset Secret to generate a new secret and add it to your script. Resetting the key will break any embeds that used the old key.

Try using the create_sso_embed_url endpoint to create your embed URL, specifying the secret in your script for the secret_id in the body of the call. The response will let you know if the secret you are using is invalid.

Is the signature string in the correct order?

The embed parameters in the signature string must be in the proper order in the URL generation script. The proper order is documented on the Single Sign-on (SSO) Embedding documentation page.

The signature string, when printed, should look something like this before it is encoded:

  company_name.looker.com
  /login/embed/embed%2Fdashboards%2F123
  "ac786cbc06162b1edde3a8b35920a93e"
  15852443573600
  "test_external_user_id"
  ["access_data","see_user_dashboards"]
  ["test_model"]
  []
  "test group space"
  {"test_user_attribute":"yes"}
  {}

After signing the signature string with your embed secret, make sure that the parameters in the final URL match the parameters specified in the signature string. Make sure that special characters such as + and / are encoded in the URL parameters (for example, the + could be interpreted as a space if it isn't properly encoded) and that there aren't any line breaks in the SSO embed URL, which could be missed after encoding.

Compare your script with our script examples to check whether your script goes through all the proper steps and whether the signature is using the proper encryption.

I'm receiving the This request includes invalid params: ["embed_domain"] error

Before you start troubleshooting the This request includes invalid params: ["embed_domain"] error, note that the embed_domain parameter is necessary only if your script is using JavaScript event listeners, which is typically not a requirement for a basic SSO embed implementation. If your application does not need to listen for JavaScript events, then the simplest option is to get rid of the embed_domain parameter completely.

If you do need to use JavaScript events in your embed application, check the URL generation script to see where the embed_domain parameter is being added. The error usually means that the embed_domain parameter was accidentally placed as an SSO parameter instead of directly within the embed_url. The script will not format the embed_domain parameter correctly unless it is actually part of the embed_url, and it should be added after the embed URL and before any parameters.

Here is what it should look like when the embed_domain parameter is specified correctly in your script:

  embed_url: "/embed/dashboards/3?embed_domain=https://company.com"

If you are using the create_sso_embed_url endpoint, the embed_domain parameter should be placed at the end of the target_url.

I'm receiving the 'nonce' param already used this hour error

The value of the nonce parameter must not be repeated within the same hour, and it needs to be less than 255 characters. Therefore, you will see this error if you are testing a URL that has already been accessed. Make sure you are generating a fresh embed URL that has not yet been loaded in your browser, and that the nonce is changing and not getting reused.

I'm getting redirected to an Uh-Oh, Something went wrong error

If you are seeing this error, please contact Looker Support to help you diagnose the issue.

I'm getting redirected to a 401 error

If you've tried all the applicable troubleshooting steps and the 401 issue persists, your browser is likely blocking third-party cookies. Most browsers are becoming more restrictive and will default to a cookie policy that blocks these cookies. For example, Safari's Prevent Cross-Site Tracking setting is enabled by default, as is Chrome's Block third-party cookies in Incognito setting.

If your application is embedding Looker content and the domain name of your Looker instance ends in company.looker.com, the browser won't authenticate the embedded iframe across domains unless the browser's cookie privacy settings are modified.

Looker-hosted instances

Looker-hosted admins who do not want to have their users manually enable third-party cookies in their browsers will need to change the domain name of the Looker-hosted instance. As an example, Looker-hosted instances typically take the format https://<company>.looker.com. If the Looker domain name is changed to https://looker.<company>.com, Looker will no longer be considered a third-party domain. See the article "What happens if the URL changes for my Looker instance?" for more information.

If you're interested in adding a custom domain for your Looker instance, reach out to Looker Support to set up the necessary DNS configuration.

Self-hosted instances

If you are self-hosting your Looker instance, make sure that your application using SSO embedding is on the same base domain as your Looker instance by changing the DNS entries for your Looker instance.

Chrome also requires that any session cookie with the samesite=none flag should also specify secure. Looker will not signal secure if your Looker instance is not provided with a --ssl-provided-externally-by=<s>startup flag, so make sure that this startup flag is configured.

I'm still having issues; what do I do now?

If you are still experiencing issues after trying the suggestions in this article, please reach out to your Looker contact, or visit Looker Support to open a ticket.