Get started with SSO embedding
Single sign-on (SSO) embedding is a way to present secure 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.
Proper hosting for SSO embedding
https://mycompany.com, you need to make sure that Looker is on a subdomain, such as
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, and to have clients from different companies or groups that should not know about one another. In this scenario, to safeguard your customers’ private information, we strongly recommend you configure Looker as a closed system, also called a multitenant installation. In a closed system, content is siloed, preventing users from different groups from knowing about each other. For this reason, we recommend 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:
- Go to the Embed page in the Admin section of Looker.
- Select Enabled from the Embed SSO Authentication drop-down, and then click Update.
- 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 example 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:
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:
|Item||Normal URL Pattern||Embed URL|
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.
- 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:
|None||Model Specific||Allows user to access data (required for viewing Looks, dashboards, or Explores)|
|Model Specific||Allows user to see LookML dashboards|
|Model Specific||Allows user to see Looks|
|Model Specific||Allows user to see user-defined dashboards and to browse folders from an embed|
|Model Specific||Allows user to see Explore pages|
|Instance Wide||Needed to create table calculations from an Explore|
|Instance Wide||Allows user to make and save changes to Looks and dashboards|
|Model Specific||Allows user to schedule dashboards and Looks to an arbitrary webhook|
|Model Specific||Allows user to schedule dashboards and Looks to an Amazon S3 bucket|
|Model Specific||Allows user to schedule dashboards and Looks to an SFTP server|
|Model Specific||Allows user to schedule dashboards and Looks to be sent to their own email (which is set with a user attribute named "email") or to an email address that is within the limitations set by the email domain allowlist. Allows user with |
|Model Specific||Allows user to schedule dashboards and Looks to be sent to any email. Allows user with |
|Model Specific||Allows user to deliver Looker content to the third-party services integrated with Looker through the Looker Action Hub. This permission is not related to data actions.|
|Instance Wide||Allows user to create alerts on dashboard tiles to receive notifications when specified conditions are met or exceeded. Users can edit, duplicate, and delete their own alerts and other users' Public alerts. If the user's Slack workspace is not connected to the Looker instance, the user will not be able to create alerts that send notifications to Slack.|
|Instance Wide||Allows user to download a query’s results with a limit applied|
|Instance Wide||Allows user to download a query’s results with no limit applied|
|Model Specific||Allows user to see the SQL for queries and any SQL errors resulting from running queries|
|Model Specific||Allows user to drill without needing to go to the full Explore page.|
|None||Instance Wide||Enables the content browser so that a user can browse folders from an embed. Any embed user granted |
To see the content in folders, the user also needs the
|None||Instance Wide||Allows user with the |
Determine which LookML models the user should have access to. This will simply be a list of model names.
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.
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 allows you to 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, called "Group", that is unique to the external group.
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
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:
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
Creating the Embed URL
An SSO embed URL has the following format:https:///login/embed/?&signature=
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
The embed URL was determined previously. It will have a format such as:
This does mean that the pattern
/embed//embed/ will show up in your final URL; this is correct.
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:
sdk=2 parameter allows Looker to 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.
The following URL parameters are used to specify the necessary information for the SSO embed:
|Parameter||Value Required?||Description||Data Type||Example|
|Yes||Any random string you like, but it cannot be repeated within an hour and must be less than 255 characters.|
This prevents an attacker from re-submitting a legitimate user's URL to gather information they shouldn't have.
|Yes||The current time as a UNIX timestamp.||Integer|
|Yes||The number of seconds that the user should remain logged in to Looker, between 0 and 2,592,000 seconds (30 days).||Integer|
|Yes||A unique identifier for the user in the application that is embedding Looker. Looker uses this value to differentiate SSO embed users.|
You create this string, and it can be any value you like. But, this value must be unique for a given set of permissions, user attributes, and models. So, for example, if the same user will have different permissions in two contexts they'll need two different external user IDs.
For security purposes, ensure that you are not using the same
|Yes||The list of permissions the user should have.|
See the Permissions section on this page for the list of allowed permissions.
|Array of strings|
|Yes||The list of model names the user should have access to.||Array of strings|
|No||The list of Looker groups the user should be a member of, if any. Use group IDs instead of group names.||Array of integers|
|No||A unique identifier for the group the user belongs to in the application that is embedding Looker, if desired.|
Users who have permission to save content, and share an external group ID, will be able to save and edit content in a shared Looker folder called "Group".
|No||The list of user attributes the user should have, if any. Contains a list of user attribute names followed by the user attribute value.|
If your LookML model is localized, you can use the
|Hash of strings|
|Yes||In Looker 3.10 this parameter was deprecated, but it is still required in the URL. Use ||Empty Placeholder|
|No||The user’s first name. If left blank, ||JSON string|
|No||The user’s last name. If left blank, ||JSON string|
|No||If you've enabled user specific time zones, sets the value of the Viewer Time Zone option in the Time Zone drop-down on the embedded Look or dashboard. This parameter does not directly change the time zone in which the content is shown; the user will need to select the desired time zone from the drop-down.|
See valid values on the SSO embedding time zone reference documentation page.
Chat team tip: If you want your embedded content to default to the viewer's time zone, use one of the following methods:
|JSON string or null|
- or -
|Yes||If a normal Looker user is already logged in to Looker, and they view an SSO embedded item, you can choose if:|
1) they should view the item with their current credentials
2) they should be logged out and logged back in with the SSO credentials.
|Boolean (true or false)|
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
To generate the signature you'll need to follow these steps.
- Gather the following parameter values in this order:
- Host, followed by
- Embed URL
- Current Time
- Session Length
- External User ID
- Group IDs
- External Group ID
- User Attributes
- Access Filters (requires an empty placeholder)
- Format all values other than Host and Embed URL as JSON
- Concatenate the values with line breaks (
- HMAC sign the concatenated string with your Looker embed secret
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:
As noted previously, it is correct for
/embed//embed/ to appear in your URL.
After you encode the URL, it would look like this:
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 interactive API documentation on your Looker instance to generate an SSO URL using this endpoint. Once generated, the SSO URL must be copied exactly and can be used only once — otherwise, it will fail. The interactive API documentation 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.