User Guide Getting Started Help Center Documentation Community Training
Single Sign-on (SSO) Embedding

Please contact your Looker account manager if you’d like to make use of these features.

Single sign-on (SSO) embedding is a way to present private, embedded Looker information 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 which information you want to share, the ID of the user in your system, and which 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

Some browsers (Internet Explorer and Safari at the time of this writing) default to a cookie policy that blocks “third-party” cookies. Since 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’d like to embed information on you’ll need to make sure that Looker is on a subdomain, such as

If Looker is hosting your instance, please reach out to Looker Support to set up the necessary DNS configuration.

If you are hosting your own instance, make sure that the application that will use SSO embedding is on the same base domain as your Looker instance.

Generating Looker’s Secret Key

In order 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 Authentication drop-down and then press Update.
  3. Press the Set 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 using the old key.

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 of 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
User-defined Dashboard
LookML Dashboard


Determine the permissions that you’ll want the user to have. The relevant permissions for SSO embedding are:

Permission Depends On Type Definition Added In
access_data None Model Specific Allows user to access data (required for viewing Looks, Dashboards, or Explore) 3.2
access_data Model Specific Allows user to see LookML dashboards 3.6
see_looks access_data Model Specific Allows user to see Looks 3.2
see_looks Model Specific Allows user to see user-defined dashboards 3.6
explore see_looks Model Specific Allows user to see Explore pages 3.2
explore Instance Wide Needed to create Table Calculations from an Explore 3.18
save_content see_looks Instance Wide Allows user to save changes to Looks and dashboards 3.8
save_content Instance Wide Allows user to schedule dashboards and Looks to an arbitrary webhook 3.46
send_to_s3 save_content Instance Wide Allows user to schedule dashboards and Looks to an Amazon S3 bucket 4.2
send_to_sftp save_content Instance Wide Allows user to schedule dashboards and Looks to an SFTP server 4.6
see_looks Model Specific Allows user to schedule dashboards and Looks to be sent to their own email (which is set via a user attribute named “email”) or to an email address that is within the limitations set by the email domain whitelist 3.8
Instance Wide Allows user to schedule dashboards and Looks to be sent to any email 3.14
see_looks Model Specific Allows user to download a query’s results with a limit applied 3.8
see_looks Model Specific Allows user to download a query’s results with no limit applied 3.8
see_sql see_looks Model Specific Allows user to see the SQL for queries and any SQL errors resulting from running queries 4.10
access_data Model Specific Allows user to drill without needing to go to the full Explore page 3.54
embed_browse_spaces None Instance Wide Enables the content browser (recommended for users who have the save_content permission) 4.8

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

However, unlike normal Looker usage, SSO embed users will not have a shared Space with members of their Looker group. Instead, use the external_group_id parameter if you want users to have a shared Space.

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, Be sure to include the port number if you haven’t enabled port forwarding, such as

Embed URL

The embed URL was determined above. 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:




The following URL parameters are used to specify the necessary information for the SSO embed:

Parameter 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 into 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.
JSON string "user-4"
permissions Yes The list of permissions the user should have.

See the permissions section above 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 Space 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. Hash of strings {
  "vendor_id" : 17,
  "company" : "acme"
access_filters Yes Though this parameter is required, it can contain an empty hash. As of Looker 3.10 that is our suggestion; user attributes are a superior way to achieve the same result.

If you do need to specify access filter fields, the first layer of the hash defines the model that the access filter field applies to, while the second level contains the names of the access filter fields and their values.
Hash of hashes {
  "model_one" : {
    "" : 17,
    "" : "acme"
  "model_two" : {
    "" : 12,
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, you may set or update the user time zone.

See valid values on the time zones page.
JSON string or null "US/Pacific"

- or -

force_logout_login Yes If a normal Looker user is already logged into 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


To generate the signature you’ll need to follow these steps.

  1. Gather the following parameter values in this order:
    • Host
    • Embed URL
    • Nonce
    • Current Time
    • Session Length
    • External User ID
    • Permissions
    • Models
    • Group IDs
    • External Group ID
    • User Attributes
    • Access Filters (if used, deprecated in 3.10)
  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 the following:
external_group_id="Allegra K"&

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

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

Testing the Embed URL

If you’d like to test your final URL you can 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.