1. Before you begin
Signed embedding is a way to present embedded Looks, visualizations, Explores, or dashboards privately to your users without requiring them to have a separate Looker login. Instead, users will be authenticated through your own application.
Signed embedding starts with 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.
- Have a running Looker instance
- Be an administrator on your Looker instance
What you'll learn
- How to setup your Looker instance to allow signed embedding
- How to generate a secret key
- Which information you'll need to collect for inclusion in your signed embed URL
- How to generate a signed embed URL
- How to add the embedded item to your application
2. Proper Looker hosting
Some browsers default to a security policy that blocks third-party cookies, which will prevent signed embedding from working. For this Codelab, the simplest way to address this issue is to temporarily allow third-party cookies in your browser:
In a production setup you must choose one of the following strategies to address third-party cookies:
- Place both your Looker instance and the application(s) where you'll use signed embedding on the same domain. For example, your Looker instance might be found at
looker.mycompany.comwhile your signed embedding site was at
- Enable the Cookieless Embed feature, which allows browsers that block third-party cookies to authenticate across different domains. Using this option does require additional configuration as detailed on Looker's Cookieless embedding documentation page.
3. Generate a secret key
To create a signed embed URL you will need a secret key from Looker. 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 select Update.
- Select the Reset Secret button in the Embed Secret section to generate your embed secret.
Copy this secret to a secure location, because you will not be able to retrieve it from Looker without resetting it. Resetting the key will break any embeds that used the old key.
4. Gather inputs to the signed embed URL
To create a signed embed URL you will need to gather the following information.
URL of the data to be displayed
Retrieve the URL of the Look, Explore, query visualization, or dashboard that you want to embed. Then remove the domain and place
/embed before the path.
https://instance_name.cloud.looker.com/looks/4 would become
https://instance_name.cloud.looker.com/explore/my_model/my_explore would become
Permissions you want the embedded user to have
Choose the permissions you would like the embedded user to have. Relevant permissions for signed embedding can be found on Looker's Signed embedding documentation page.
For the purposes of this Codelab the following permissions are likely to be a minimum viable list:
If you would like to test an embed users ability to browse and save content, you may also wish to consider:
Model access you want the embedded user to have
Choose the Looker models you would like the embedded user to have access to. At the least, the user should have access to the model that underlies the Look, Explore, query visualization, or dashboard that you chose to display.
User attributes you want the embedded user to have
Choose the Looker user attributes you would like the embedded user to have, if any. For this Codelab it may not be necessary to add any user attributes.
Groups you want the embedded user to have
Determine which group IDs (not group names) the user should belong to, if any. For this Codelab it may not be necessary to add any groups.
Your company's user ID and group
Looker signed embed URLs require you to provide a unique identifier for each user in your application that views an embedded Looker element. Looker calls this the "external user ID" and it may be any string.
If relevant, you can also provide an "external group ID." This is a unique identifier for the group that the user belongs to in your application.
5. Choose your URL generation script
Building a proper signed embed URL will require you to use code, so that you can properly encode the URL with your secret key and generate other security-related items.
Fortunately, several sample scripts in various programming languages are available in Looker's looker_embed_sso_examples Github repository. Choose the script that is relevant to you and copy it into your development environment.
6. Fill in data and run script
The URL generation script that you chose will have variables or an object in which you can place all of your previously collected information, along with examples for how that information should be presented:
Apx. rows for your input
15 - 28
18 - 35
193 - 202
87 - 104
103 - 111
88 - 101
14 - 27
After replacing the examples with the data that you collected, run the script to generate your signed embed URL. Make note of the URL for the next step.
7. Test the URL
To test your final URL, paste it into the Embed URI Validator on the Embed page of Looker's Admin section. While this feature can't determine if the data and permissions you envision have been set up correctly, it can validate that your authentication is working properly.
8. Embed the URL in an iframe
Finally, embed your Look, Explore, query visualization, or dashboard into your application by adding the URL you generated to the
src attribute of an
iframe. Place that iframe into your application or test environment.
9. Additional information
Looker's signed embedding feature should be carefully configured to ensure that embedded users are limited to your desired data visibility and permissions. Please consider the following:
- Looker's Signed embedding documentation page provides in-depth details about how a signed embed URL should be generated, along with all available configuration options.
- Looker's Security best practices for embedded analytics documentation page provides guidance for securely configuring signed embedding.
- Signed embedding is often used by Looker customers to present data to their own clients, while requiring that clients from different companies or groups not know about one another. In this scenario we strongly recommend that you configure Looker as a closed system, sometimes called a "multitenant installation."
- Signed embedding functionality is available via Looker's API.