Single Sign-on (SSO) Embedding

On this Page
Docs Menu
  • Explore
  • Develop
  • Administer
  • Setup
  • 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 setup 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 dropdown 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 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
    see_lookml_
    dashboards
    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_user_
    dashboards
    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
    create_table_
    calculations
    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
    send_outgoing_
    webhook
    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
    schedule_look_
    emails
    save_content 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
    schedule_external_
    look_emails
    schedule_look_
    emails
    Instance Wide Allows user to schedule dashboards and Looks to be sent to any email 3.14
    download_with_
    limit
    see_looks Model Specific Allows user to download a query’s results with a limit applied 3.8
    download_without_
    limit
    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
    see_drill_
    overlay
    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.

    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.

    However, unlike normal Looker usage, SSO embed users will not inherit permissions from their Looker groups, nor will they have a shared Space with member of their Looker group.

    Instead, any permissions must be assigned explicitly to SSO embed users, and you will 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

    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:

    • /embed/looks/4
    • /embed/explore/my_model/my_explore
    • /embed/dashboards/1
    • /embed/dashboards/my_model::my_dashboard

    This does mean that the pattern /embed//embed/ will show up in your URL; this is correct.

    Parameters

    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.

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

    As noted above, users will not inherit permissions from these groups.
    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 No AVOID AS OF3.10 The list of access filter fields the user should have, if any. 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 timezones, you may set or update the user timezone.

    See valid values on the timezones 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

    Signature

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

    1. Gather the following parameter values in this order:
      • Host
      • Embed Path
      • 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 the values 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
    
    Still have questions?
    Go to Discourse - or - Email Support
    Top