User Guide Getting Started Help Center Documentation Community Training
Looker
  
English
Français
Deutsch
日本語
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 https://mycompany.com you’ll need to make sure that Looker is on a subdomain, such as https://analytics.mycompany.com.

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

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

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
Look https://mycompany.looker.com/
looks/4
/embed/looks/4
Explore https://mycompany.looker.com/
explore/my_model/my_explore
/embed/explore/my_model/my_explore
User-defined dashboard https://mycompany.looker.com/
dashboards/1
/embed/dashboards/1
LookML dashboard https://mycompany.looker.com/
dashboards/my_model::my_dashboard
/embed/dashboards/my_model::my_dashboard

Permissions

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 Spaces 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 Instance Wide Allows user to schedule dashboards and Looks to an arbitrary webhook
send_to_s3 see_looks Instance Wide Allows user to schedule dashboards and Looks to an Amazon S3 bucket
send_to_sftp see_looks Instance Wide 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 via a user attribute named “email”) or to an email address that is within the limitations set by the email domain whitelist
schedule_external_look_emails schedule_look_
emails
Instance Wide Allows user to schedule dashboards and Looks to be sent to any email
download_with_limit see_looks Model Specific Allows user to download a query’s results with a limit applied
download_without_limit see_looks Model Specific 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
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 Spaces from an embed. (embed_browse_spaces is recommended for users who have the save_content permission, so that the user can browse Spaces when selecting where to save content).

NOTE: In order to see the content in Spaces, the user also needs the see_looks, see_user_dashboards, and see_lookml_dashboards permissions.

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.

Groups

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.

SSO embed users will have access to any shared Space with members of their Looker group. 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 Space that is unique to the external group.

Creating the Embed URL

An SSO embed URL has the following format:

https://HOST/login/embed/EMBED URL?PARAMETERS&signature=SIGNATURE

Host

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

/embed/looks/4

/embed/looks/4?embed_domain=https://mywebsite.com

If you are using the embed SDK be sure to add the embed_domain and also include sdk=1 to the end of the embed URL, like this:

/embed/looks/4

/embed/looks/4?embed_domain=https://mywebsite.com&sdk=1

The sdk=1 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 part of the signed SSO URL.

Parameters

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 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 [
  "access_data",
  "see_looks"
]
models Yes The list of model names the user should have access to. Array of strings [
  "model_one",
  "model_two"
]
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" : {
    "vendor.id" : 17,
    "company.name" : "acme"
  },
  "model_two" : {
    "vendor.id" : 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, this 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 time zones page.
JSON string or null "US/Pacific"

- or -

null
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

or

2) they should be logged out and logged back in with the SSO credentials.
Boolean (true or false) true

All of the above 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 {}.

Signature

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

Encoding

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:

https://analytics.mycompany.com/login/embed//embed/dashboards/1?
nonce="22b1ee700ef3dc2f500fb7"&
time=1407876784&
session_length=86400&
external_user_id="user-4"&
permissions=["access_data","see_user_dashboards","see_looks"]&
models=["model_one","model_two"]&
group_ids=[4,3]&
external_group_id="Allegra K"&
user_attributes={"vendor_id":17,"company":"acme"}&
access_filters={"model_one":{"vendor.id":17,"company.name":"acme"},
  "model_two":{"vendor.id":12,"company.name":"widgets-r-us"}}&
first_name="Alice"&
last_name="Jones"&
user_timezone="US/Pacific"&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL

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

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

https://analytics.mycompany.com/login/embed/%2embed%2Fdashboards%2F1?
nonce=%2222b1ee700ef3dc2f500fb7&%22&
time=1407876784&
session_length=86400&
external_user_id=%22user-4%22&
permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%2C%22see_looks%22%5D&
models=%5B%22model_one%22%2C%22model_two%22%5D&
group_ids=%5B4%2C3%5D&
external_group_id=%22Allegra%20K%22&
user_attributes=%7B%22vendor_id%22%3A17%2C%22company%22%3A%22acme%22%7D&
access_filters=%7B%22model_one%22%3A%7B%22vendor.id%22%3A17%2C%22company.name%22%3A%22acme%22%7D%2C
  %22model_two%22%3A%7B%22vendor.id%22%3A12%2C%22company.name%22%3A%22widgets-r-us%22%7D%7D&
first_name=%22Alice%22&
last_name=%22Jones%22&
user_timezone=%22US%2FPacific%22&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL

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.

Top