Contact your Looker account manager if you want to make use of these features.

Single sign-on (SSO) embedding is a way to present private embedded Looks, Explores, dashboards, or LookML dashboards to your users without requiring them to have a separate Looker login. Instead, users will be authenticated through your own application.

SSO embedding works by creating a special Looker URL that you will use in an iframe. The URL contains the information you want to share, the ID of the user in your system, and the permissions you want that user to have. You’ll then sign the URL with a secret key provided by Looker.

For public embedding, see the Public embedding with iframe tags section of the Public sharing, importing, and embedding of Looks documentation page.

Proper hosting for SSO embedding

Some browsers — for example, Safari, or browsers with ad or tracking-blocking extensions installed — default to a cookie policy that blocks third-party cookies. If your Looker admin has enabled the Embed Cookieless Authentication Labs feature, manually enabling third-party cookies is not required for user authentication and navigation through embedded Looker content. When Embed Cookieless Authentication is enabled, browser navigation controls, such as the forward and back arrows, will not work for certain types of navigation, such as navigation between dashboards, Looks, and Explores.

If the Embed Cookieless Authentication Labs feature is not enabled, Looker will use cookies for user authentication. In this case, attempting to authenticate the embedded iframe across domains is not possible in these browsers (unless the user modifies their browser’s cookie privacy settings). For example, if you want to embed information on https://mycompany.com, you need to make sure that Looker is on a subdomain, such as https://analytics.mycompany.com.

If Looker is hosting your instance, contact Looker Support to set up the necessary DNS configuration. Open a support request in Looker’s Help Center by clicking Contact Us.

If you have a customer-hosted Looker instance, make sure that the application that will use SSO embedding is on the same base domain as your Looker instance.

Controlling client visibility with a closed system

It is common in an SSO embed configuration for Looker users to present data to their own customers while having clients from different companies or groups who should not know about one another. In this scenario, to safeguard your customers’ private information, we strongly recommend that you configure Looker as a closed system, also called a multitenant installation. In a closed system, content is siloed to prevent users from different groups from knowing about each other. For this reason, we recommend that you enable the Closed System option before you grant any external users access to your instance.

For more information, see the Designing and configuring a system of access levels and the Security best practices for embedded analytics documentation pages.

Generating Looker’s secret key

To validate that an SSO embedding request is legitimate and hasn’t been forged by someone else, you’ll first need to generate an “embed secret.” To do so:

1. Go to the Embed page in the Admin section of Looker.
2. Select Enabled from the Embed SSO Authentication drop-down, and then click Update.
3. Click the Reset Secret button to generate your embed secret. Be sure to copy this secret to a secure location, because you will not be able to retrieve it from Looker again without resetting it. Resetting the key will break any embeds that used the old key.

Anyone with access to the secret key may create a URL to access any model that Looker instance is connected to, as any user, with any permission. Protect the SSO embed secret as you would admin credentials to your embedded Looker instance, and keep SSO embedding disabled if you’re not using it.

Building the Embed URL

Building the proper URL will require you to write code, so that you can properly encode the URL with your secret key and generate other security-related items. You can find several sample scripts on our SSO examples GitHub repository. The following sections explain the information that you’ll need to supply to those scripts.

Collecting the necessary Looker information

As a starting point for building your URL, you’ll first want to determine all the information that will need to be included. You will need:

Embed URL

Retrieve the URL of the Look, Explore, or dashboard that you want to embed. Then remove the domain and place /embed before the path, as follows:

Embedded content always reflects the production version of the content. Any changes made while in Development Mode that affect content and that have not been deployed to production will not appear in an embed.

Permissions

A permission set defines what a user or group can do. Permissions can be applied in one of two ways:

• Model Specific: This type of permission is applied only to the model sets that are part of the same role.
• Instance Wide: This type of permission applies to the Looker instance as a whole. Embed users with instance-wide permissions can perform certain functions across the entire Looker instance, but cannot access content based on models not included in their role’s model set.

Determine the permissions that you’ll want the user to have. The following list shows all available permissions for SSO embedding. Permissions that are not on the following list are not supported for SSO embedding:

Model access

Determine which LookML models the user should have access to. This will simply be a list of model names.

User attributes

Determine which user attributes the user should have, if any. You’ll need the name of the user attribute from Looker, as well as the value that the user should have for that attribute.

Groups

Determine which groups the user should belong to, if any. You’ll need the group IDs as opposed to the group names. Adding an SSO embed user to a Looker group lets you manage that user’s access to Looker folders. SSO embed users will have access to any folders shared with members of their Looker groups.

You can also use the external_group_id parameter to create a group that is external to the regular Looker groups. In that case, SSO embed users with the same external_group_id will have access to a shared folder, named “Group,” that is unique to the external group.

Embedded roles

The permissions and models parameters create a role for the embed user. This role appears as an “Embedded Role” in the Users page in Lookers Admin section. If the permissions, models, and group_ids parameters are all specified in the embed URL, then the embedded role is additive to any roles already assigned to the groups listed in the group_ids parameter. This is the same as standard roles in that all roles in Looker are additive.

For example, say you have an existing group in Looker with the group ID 1, and that group already has the explore permission for a model named model_one, and you create an embed URL with the following parameters:

• group_ids = [1]
• permissions = ["access_data","see_looks"]
• models = ["model_two"]

In that case, the embed user will inherit the ability to view and explore the data on model_one, and the embed role created with the preceding parameters will also grant the ability to view the data on model_two.

Creating the Embed URL

An SSO embed URL has the following format:

https://HOST/login/embed/EMBED URL?PARAMETERS&signature=SIGNATURE

Host

The host is the location where your Looker instance is being hosted. For example, analytics.mycompany.com. Be sure to include the port number if you haven’t enabled port forwarding, such as analytics.mycompany.com:9999.

Embed URL

The embed URL was determined previously. It will have a format such as:

• /embed/looks/4
• /embed/explore/my_model/my_explore
• /embed/dashboards/1 or /embed/dashboards-legacy/1
• /embed/dashboards/my_model::my_dashboard or /embed/dashboards-legacy/my_model::my_dashboard

This does mean that the pattern /embed//embed/ will show up in your final URL; this is correct.

If you are using embedded JavaScript events be sure to add an embed_domain (the domain where the iframe is being used) to the end of the embed URL, like this:

embed_domain is added after the embed URL, and before any parameters. So if you had existing parameters, such as nonce=62, the addition of the embed_domain would look like:

If you are using the Embed SDK be sure to add the embed_domain and also include sdk=2 to the end of the embed URL, like this:

The sdk=2 parameter lets Looker identify that the SDK is present and can take advantage of additional features provided by the SDK. The SDK cannot add this parameter itself because it is part of the signed SSO URL.

Parameters

The following URL parameters are used to specify the necessary information for the SSO embed:

All the preceding parameters are required, but any parameter with “No” in the “Value Required?” column can be used with an empty value. For example, you could use group_ids [] or user_attributes {}.

Signature

To generate the signature you’ll need to follow these steps.

1. Gather the following parameter values in this order:
   • Host, followed by login/embed/ (for example, analytics.mycompany.com/login/embed/)
   • Embed URL
   • Nonce
   • Current Time
   • Session Length
   • External User ID
   • Permissions
   • Models
   • Group IDs
   • External Group ID
   • User Attributes
   • Access Filters (requires an empty placeholder)
2. Format all values other than Host and Embed URL as JSON
3. Concatenate the values with line breaks (\n)
4. HMAC sign the concatenated string with your Looker embed secret

Encoding

The final step is to URL encode your URL.

Before you encode the URL, a properly formatted embed URL that uses all possible parameters might look like this:

https://analytics.mycompany.com/login/embed//embed/dashboards/1?
nonce="22b1ee700ef3dc2f500fb7"&
time=1407876784&
session_length=86400&
external_user_id="user-4"&
permissions=["access_data","see_user_dashboards","see_looks"]&
models=["model_one","model_two"]&
group_ids=[4,3]&
external_group_id="Allegra K"&
user_attributes={"vendor_id":"17","company":"xactness"}&
access_filters={}&
first_name="Alice"&
last_name="Jones"&
user_timezone="US/Pacific"&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL

As noted previously, it is correct for /embed//embed/ to appear in your URL.

After you encode the URL, it would look like this:

https://analytics.mycompany.com/login/embed/%2embed%2Fdashboards%2F1?
nonce=%2222b1ee700ef3dc2f500fb7&%22&
time=1407876784&
session_length=86400&
external_user_id=%22user-4%22&
permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%2C%22see_looks%22%5D&
models=%5B%22model_one%22%2C%22model_two%22%5D&
group_ids=%5B4%2C3%5D&
external_group_id=%22Allegra%20K%22&
user_attributes=%7B%22vendor_id%22%3A%2217%22%2C%22company%22%3A%22xactness%22%7D&
access_filters%7B%7D%26%0A
first_name=%22Alice%22&
last_name=%22Jones%22&
user_timezone=%22US%2FPacific%22&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL

Using the create_sso_embed_url API endpoint

The Looker API includes the create_sso_embed_url endpoint, which takes a set of SSO embed parameters that includes the URL of the content you want to embed and returns a complete, encoded, cryptographically signed SSO URL.

To use this API endpoint from a web server, the web server must be able to authenticate into the Looker API with admin privileges. The web server domain must also be listed in the Embed Domain Allowlist.

You can also use the API Explorer to generate an SSO URL that uses this endpoint. You can install the API Explorer on your Looker instance from the Looker Marketplace, or you can view a public version on Looker’s Developer Portal. Once generated, the SSO URL must be copied exactly and can be used only once — otherwise, it will fail. The API Explorer is also useful for generating an SSO URL and comparing it to a manually created SSO URL for troubleshooting purposes.

For more information about the Looker API, see the Getting started with the Looker API documentation page.

Testing the Embed URL

To test your final URL, paste it into the Embed URI Validator on the Embed page of Looker’s Admin section. While this option can’t tell you if the data and permissions you envision have been set up correctly, it can validate that your authentication is working properly.