home User Guide Getting Started Help Center Documentation Community Training Certification
Looker keyboard_arrow_down
language keyboard_arrow_down
Single sign-on (SSO) embedding

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 (Internet Explorer and Safari at the time of this writing) default to a cookie policy that blocks third-party cookies. Because Looker uses cookies for user authentication, 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, 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:

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

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:

Item Normal URL Pattern Embed URL
Look https://instance_name.looker.com/
Explore https://instance_name.looker.com/
User-defined dashboard https://instance_name.looker.com/
User-defined legacy
LookML dashboard https://instance_name.looker.com/
Legacy LookML

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.


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

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:

Permission Depends On Type Definition
access_data None Model Specific Allows user to access data (required for viewing Looks, dashboards, or Explores)
see_lookml_dashboards access_data Model Specific Allows user to see LookML dashboards
see_looks access_data Model Specific Allows user to see Looks
see_user_dashboards see_looks Model Specific Allows user to see user-defined dashboards and to browse folders from an embed
explore see_looks Model Specific Allows user to see Explore pages
create_table_calculations explore Instance Wide Needed to create table calculations from an Explore
save_content see_looks Instance Wide Allows user to make and save changes to Looks and dashboards
send_outgoing_webhook see_looks Model Specific Allows user to schedule dashboards and Looks to an arbitrary webhook
send_to_s3 see_looks Model Specific Allows user to schedule dashboards and Looks to an Amazon S3 bucket
send_to_sftp see_looks Model Specific Allows user to schedule dashboards and Looks to an SFTP server
schedule_look_emails see_looks 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 create_alerts permissions to send alert notifications to an email address that is within the limitations set by the email domain allowlist.
schedule_external_look_emails schedule_look_
Model Specific Allows user to schedule dashboards and Looks to be sent to any email. Allows user with create_alerts permissions to send alert notifications to any email domain.
see_looks Model Specific ADDED6.22 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.
create_alerts see_looks Instance Wide ADDED6.22 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.
download_with_limit see_looks Instance Wide Allows user to download a query’s results with a limit applied
download_without_limit see_looks Instance Wide Allows user to download a query’s results with no limit applied
see_sql see_looks Model Specific Allows user to see the SQL for queries and any SQL errors resulting from running queries
clear_cache_refresh access_data Model Specific ADDED21.14 Users can clear cache and refresh embedded dashboards, legacy dashboards, dashboard tiles, Looks, and Explores. The Clear cache and refresh permission Labs feature first must be enabled for this permission to be enabled.
see_drill_overlay access_data Model Specific Allows user to drill without needing to go to the full Explore page.
embed_browse_spaces None Instance Wide Enables the content browser so that a user can browse folders from an embed. Any embed user granted embed_browse_spaces permission is given access to a personal embed folder and to your organization’s Shared folder, if there is one.

The embed_browse_spaces permission is recommended for users who have the save_content permission, so that the user can browse folders when selecting where to save content.

To see the content in folders, the user also needs the see_looks, see_user_dashboards, and see_lookml_dashboards permissions.
embed_save_shared_space None Instance Wide ADDED21.4 Allows user with the save_content permission to save content to the organization’s Shared folder, if there is one. Users who have the save_content permission but not the embed_save_shared_space permission will only have the option to save content to their personal embed folder.

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.


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.

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:

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


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:

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 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
nonce 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.
JSON String "22b1ee700ef3dc2f500fb7"
time Yes The current time as a UNIX timestamp. Integer 1407876784
session_length Yes The number of seconds that the user should remain logged in to Looker, between 0 and 2,592,000 seconds (30 days). Integer 86400
external_user_id 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 external_user_id across different embed sessions for different interactive users.
JSON string "user-4"
permissions 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 [
models Yes The list of model names the user should have access to. Array of strings [
group_ids 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 [4, 3]
external_group_id 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”.
JSON string "Accounting"
user_attributes 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 locale user attribute in the embed URL to specify a language for the embed. For example, including the parameter user_attributes { "locale" : "fr_FR" } would cause the embed to load French as its language.
Hash of strings {
  "vendor_id" : "17",
  "company" : "xactness"
access_filters Yes In Looker 3.10 this parameter was removed, but it is still required in the URL. Use access_filters with an empty placeholder, for example access_filters={}. Empty Placeholder {}
first_name No The user’s first name. If left blank, first_name will retain the value from the last request, or be “Embed” if no first name has ever been set. JSON string "Alice"
last_name No The user’s last name. If left blank, last_name will retain the value from the last request, or be “Embed” if no last name has ever been set. JSON string "Jones"
user_timezone 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:

  • Add the parameter ?query_timezone=user_timezone to the embed URL. For example:

  • Save the embedded dashboard or Look with the default time zone set to Viewer Time Zone, which will use the user’s time zone by default for both embed users and non-embed users.
  • JSON string or null "US/Pacific"

    - or -

    force_logout_login 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) true

    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 {}.


    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


    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:

    external_group_id="Allegra K"&

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

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


    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 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.