Creating a signed embedded Looker iFrame for testing

robertcarr · 09-13-2024 05:58 PM

Author: Rob Carr, Customer Engineer, Cloud BI

Introduction

Looker allows companies to leverage its governed and secure modeling layer to provide data within customer facing applications or portals. This can be an exciting way for Looker users to further expand their own product offering with their customers and offer more value within their application. One way of doing this with really quick time to value is using Looker’s signed iFrame URLs to embed content (Dashboards/Looks) or Explores. This article is going to give a quick overview of how you can test this approach within Looker and some of the functionality it provides.

The recommended method for creating the signed embed URL in production is to use the create_signed_embed_url endpoint on the backend. For testing, we can use the Looker application itself to generate a signed URL. There are two ways to do this;

From an Explore or Dashboard, we can select Get embed URL or;
We can use the Looker API Explorer.

We’re going to talk through the former as it’s the easiest way to generate a signed embed URL for testing.

Section 1: Creating the signed embed URL for testing

First off, the user creating the signed embed URL needs the manage_embed_settings permission to generate the URL. In production, this is also the permission the user authenticated into the API would need to create the signed embed URL. For API authentication, see these docs.

To create the signed embed URL, we can click the three dots on the dashboard we want to embed and then select Get embed URL.

This will open both a private embed and signed embed option. We are going to focus on the signed embed.
Example:

In the example above, we have a number of parameters we can customize but the full extensive list is included in the API request body here.

Content URL: This is the embedded URL for the dashboard or explore you want to embed
Apply theme to dashboard URL: Embedded content in Looker can have additional theming capabilities applied, this is a pre-created theme but you can always include theme settings in the URL itself by using the _theme element.
External User ID: This is the unique ID associated with the embed user. It is different to user id.
First Name & Last Name: Names associated with the user.
External Group ID: This is the unique External Group ID associated with the embed user. It is different from group id. It essentially creates a tenant structure for all users associated with that external group ID to save and share content only amongst themselves.
Models: The list of model names the user should have access to.
Permissions: These are the Looker permissions a user will have. We will talk a little later about how you can include additional experiences for the user by leveraging these. We can also assign permissions to groups and use group IDs (not external group IDs) to associate embed users with a set of permissions or user attributes, rather than passing them through the URL.
User Attributes: The list of user attributes the user should have, if any.
Session Length: The number of seconds that the user should remain logged in to Looker, between 0 and 2,592,000 seconds (30 days).

Section 2: External group ID & permissions

You can see in the example above, we assigned the user to the external group ID ‘CommunityUsersTestGroup’. If we align this with the correct permissions, we can create additional functionality within the embedded iFrame. First off, if the user has the embed_browse_spaces permission, they can see the folder structure similar to the below. They will also have a ‘Group’ folder associated with their external group ID i.e. anyone with the same external group ID value has access to the same Group folder.

Now, if we combine this permission with the explore, save_content and embed_save_shared_space permissions, the user can not only explore and ask questions of the data themselves, they can then save this content down to their own personal folder, called ‘My Folder’ and to the ‘Group’ folder mentioned above for other individuals in their tenant to access the content they created. This can take a large burden away from the Looker customer and allow their own external customers to get additional functionality and value from the application itself, especially for those more data driven users.

From an admin perspective, we can view all of these embed user and group folders from within the All Folders space. This allows us to see what our customers are creating within their own folder structures. In the second screenshot below, you can see we now have an embed group folder called CommunityUsersTestGroup associated with the user above.

Section 3: User Attributes

User attributes can have many functionalities within Looker, such as setting up dynamic database connections and data actions, see full list here. However, from an embedded iFrame perspective, one of the most common use cases is creating row level security. This is done by using an access filter in the relevant LookML explore. Ensure you have a user attribute created first before trying to set the users values in the create_signed_embed_url endpoint call.

For the example above, we can see we assigned our user the value ‘Calvin Klein’ to our user attribute called brand. In the LookML explore, an access filter is set up by telling Looker what field to filter and what user attribute value to check against. This essentially adds a hidden where clause to the underlying SQL Looker generates, which your end customers would not have access to view. An example is outlined below where we filter the brand field from the products view within the Orders, Items and Users explore using the value from the brand user attribute. In our example above, everything for our embed user would be filtered where the brand is Calvin Klein.

Conclusion: signed embed iFrame URL output

You will notice that Looker outputs a signed embed URL. This is signed with the embed secret to ensure it is secured. When you make the create_signed_embed_url endpoint call, Looker grabs the latest embed secret so you do not need to store this anywhere or pass it through any of the API calls. For testing the URL here, you can open it in an incognito tab.You will also notice the url has /login and /embed/. /login is required to log the user into Looker and /embed is required to create the iFrame. Any subsequent embedded content that is accessed during the user’s session can be accessed using Private iFrames, meaning we don’t need to run an API call for any of the subsequent embedded content, provided we don’t have a reason that requires updating the user information.

You can also see that we are provided both with an SDK Call code and Embed SDK Call code. The SDK Call code is associated with the API SDKs and is used on the backend (server side). The Embed SDK Call code is for the embed SDK and should be used on the front-end (client side). It is recommended to use these in tandem when embedding Looker content.

Troubleshooting

If you want to troubleshoot the signed embed URL your code is generating and whether or not it is valid, your Looker instance has an Embed URI Validator to do just that. This will let you know if the URL is valid or not. If not, something else may be causing the issues, at which point you should contact support or your Looker representative for more help.