Signed Embedding with Looker

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.

This Codelab is intended to demonstrate basic signed embedding as quickly as possible. It does not detail security or data privacy considerations for a production implementation. Please review the items in the Additional information section before your final implementation.

Prerequisites

• 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:

• Enable cookies in Chrome
• Enable cookies in Firefox
• Enable cookies in Safari

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.com while your signed embedding site was at analytics.mycompany.com.
• 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:

1. Go to the Embed page in the Admin section of Looker.
2. Select Enabled from the Embed SSO Authentication drop-down, and then select Update.
3. 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.

Anyone with the secret key may create a URL with access to any Looker model, as any user, with any permission. Protect the signed embed secret as you would Looker admin credentials.

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.

For example, https://instance_name.cloud.looker.com/looks/4 would become /embed/looks/4.

Or, https://instance_name.cloud.looker.com/explore/my_model/my_explore would become /embed/explore/my_model/my_explore.

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:

• access_data
• see_lookml_dashboards
• see_looks
• see_user_dashboards
• explore

If you would like to test an embed users ability to browse and save content, you may also wish to consider:

• save_content
• embed_browse_spaces
• embed_save_shared_space

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:

Script name	Apx. rows for your input
LookerEmbedClientExample.java	15 - 28
csharp_example.cs	18 - 35
go_example.go	193 - 202
node_example.js	87 - 104
python_example.py	103 - 111
ruby_example.rb	88 - 101
sso_embed.php	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.

Be mindful where you embed your Codelab URL. If the iframe will be accessible by anyone other than yourself, that person will gain the permissions and data access that you have configured.

If desired, you may interact with the iframe using javascript by utilizing Looker's Embedded JavaScript events.

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.