This page describes how to configure Looker to authenticate users using the Security Assertion Markup Language (SAML). It includes instructions for linking SAML groups to Looker roles and permissions.
SAML & Identity Providers
- Companies use different Identity Providers (for example, Okta or OneLogin) to coordinate with SAML. The terms used in the following set-up instructions and in the UI may not directly match those used by your Identity Provider. For clarifications during set up, contact your internal SAML or authentication team or reach out to Looker Support.
- Looker assumes that SAML requests and assertions will be compressed; ensure that your Identity Provider (IdP) is configured as such. Currently, Looker’s requests to the IdP are not signed.
- Looker does support Identity Provider-initiated login.
- Some of the set up process must be completed on the Identity Provider’s website.
- Okta now offers a Looker App, which is the recommended way to configure Looker and Okta together. If you would prefer to create the app yourself, you can follow our previous directions here: Configure Looker + Okta via template (recommended) or by creating a new app.
Setting Up Looker on Your Identity Provider
Your SAML IdP will need to know the Looker instance URL to which the SAML IdP should POST SAML assertions. In your IdP this might be called “Post Back URL,” “Recipient,” or “Destination,” among other names.
The information to provide is the URL where you typically access your Looker instance via the browser, followed by
/samlcallback. For example:
Some IdPs also require you add
:9999 after your instance URL. For example:
Other Things to Keep in Mind
- Looker requires SAML 2.0.
- Don’t disable SAML authentication while you are logged into Looker via SAML unless you have an alternate account login set up. Otherwise, you could lock yourself out of the app.
- Looker can migrate existing accounts to SAML via email addresses that come from either current Email/Password setups, LDAP, or Google Auth. You will be able to configure this in the setup process.
SAML Authentication needs to first be licensed by Looker. Please contact your Account Manager or
firstname.lastname@example.org to update your license for this feature.
Once your license is updated, navigate to the SAML Authentication page in the Admin section of Looker, then click on the Enabled button to see the following configuration options. Note that any changes to configuration options do not take effect until you click the Update button at the bottom of the page.
SAML Auth Settings
If your Identity Provider makes it difficult to obtain the three fields called for below, it may offer an IdP metadata xml document, which contains all the same information. Either fill out the three fields below from the output obtained during the Identity Provider configuration process for Looker on the IdP side or upload the xml file generated during the same session. You do not need to complete both steps.
IdP Metadata: Either paste the public URL of the .xml document that contains the IdP information, or paste the document’s text in its entirety here. Looker will parse that file to populate the required fields.
IdP URL: The URL where Looker will go to authenticate users. This is called the “Redirect URL” in Okta.
IdP Issuer: The unique identifier of the IdP. This is called “External Key” in Okta.
IdP Certificate: Public Key to let Looker verify the signature of IdP responses.
Taken together, these fields let Looker confirm that a set of signed SAML assertions actually came from an Identity Provider (IdP) that Looker trusts.
SP Entity / IdP Audience: This field is not required by Looker, but many IdPs will require this field. If you enter a value in this field, that value will be sent to your IdP as Looker’s
Entity ID in authorization requests. In that case, Looker will only accept authorization responses that have this value as the
Audience. If your IdP requires an
Audience value, enter that string here.
This value is also used as the “issuer” field in messages sent to the IdP. So, if your IdP complains that it is receiving a message without an “issuer” then you need to fill this in. You can use whatever string your IdP might require. In most cases you can use “Looker”. If this field is present then your IdP must send it as the “audience” field in the message it sends back to Looker.
Allowed Clock Drift: The number of seconds of clock drift (the difference in timestamps between the IdP and Looker) allowed. This value will usually be the default of 0, but some IdPs may require extra leeway for successful logins.
User Attributes Settings
In the following fields, specify the attribute name in your IdP’s SAML configuration that contains the corresponding information for each field. Entering the SAML attribute names tells Looker how to map those fields and extract their information at login time. Looker isn’t particular about how this information is constructed, it’s just important that the way you input it into Looker matches the way that the attributes are defined in your IdP. Looker provides default suggestions about how to construct those inputs
Email attr: Specify the attribute name your IdP uses for user email addresses.
FName attr: Specify the attribute name your IdP uses for user first names.
LName attr: Specify the attribute name your IdP uses for user last names.
Pairing SAML Attributes with Looker User Attributes
You can optionally use the data in your SAML attributes to automatically populate values in Looker user attributes when a user logs in. For example, if you have configured SAML to make user-specific connections to your database, you could pair your SAML attributes with Looker user attributes to make your database connections user-specific in Looker.
To pair SAML attributes with corresponding Looker user attributes:
- Enter the name of the SAML attribute in the SAML Attribute field and the name of the Looker user attribute you want to pair it with in the Looker User Attributes field.
- Check Required if you want to require that the SAML attribute has a value in order for a user to log in.
- Click + and repeat these steps to add more attribute pairs.
You have the option to assign Looker roles to users based on their SAML groups. If you choose not to use this option, leave the toggle on OFF, and choose the default role and group that all new users will receive:
If you do choose to use SAML groups to define roles, set the toggle to ON. Keep in mind that all other roles will be overridden by the SAML authorized roles if this feature is on. Looker displays these settings:
Group Finder Strategy: Select the system the IdP uses to assign groups, which depends on your IdP.
Almost all IdPs use a single attribute value to assign groups, as shown in this sample SAML assertion:
<saml2:Attribute Name='Groups'> <saml2:AttributeValue >Everyone</saml2:AttributeValue> <saml2:AttributeValue >Admins</saml2:AttributeValue> </saml2:Attribute>
In this case, select
Groups as values of single attributes.
Some IdPs use a separate attribute for each group, and then require a second attribute to determine whether a user is a member of a group. Below is a sample SAML assertion showing this system:
<saml2:Attribute Name='group_everyone'> <saml2:AttributeValue >yes</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute Name='group_admins'> <saml2:AttributeValue >no</saml2:AttributeValue> </saml2:Attribute>
In this case, select
Groups as individual attributes with membership value.
Groups Attribute: Looker displays this field when the Group Finder Strategy is set to
Groups as values of single attribute. Enter the name of the groups attribute used by the IdP.
Group Member Value: Looker displays this field when the Group Finder Strategy is set to
Groups as individual attributes with membership value. Enter the value that indicates a user is a member of a group.
Auth Requires Role: Setting this to ON means that users are required to have a role in order to log into Looker. If it is set to OFF, that means your SAML users can authenticate to Looker even if they have no role assigned. Having no role set means that a user will not be able to see any data or take any action in Looker.
Group to Role Pairings
Next, input the groups as they are expressed in your SAML IdP, and then select a Looker role from the dropdown. Any user who is a member of the SAML group will be assigned the Looker roles outlined here. You can input more than one role in each role box. Roles are additive — a user gets the all of the roles specified.
To add an additional group to role pairing, click the + sign to the right of the role input box.
Test User Authentication
Read the results of the test carefully, as some parts of the test can succeed even if others fail.
Tests will redirect out to the server and will open a browser tab. The tab displays:
- That Looker was able to talk to the server and validate
- The names it gets from the server. You need to validate that it returns the proper results.
- A trace to show how the info was found. Use this to troubleshoot if the information is incorrect. If you need additional information, you can read the raw XML server file.
- You can run this test any time, even if SAML is partially configured. Running a test can be helpful during configuration to see which parameters need configuration.
- The test uses the settings entered in the SAML Authentication page, even if those settings have not been saved. The test will not affect or change any of the settings in that page.
A Note About Looker Groups
If you have set Set Roles from Groups to ON, then Looker will make one Looker group for every SAML group that is introduced into the system as specified above. Those Looker groups can be viewed on the Groups page of the Admin section of Looker. Groups can be used for setting Content Access Controls and assigning User Attributes.
If you have set Set Roles from Groups to OFF, you can set a default group for SAML users.
Migration & Integration Options
Looker recommends that you enable Alternate Login and provide a merging strategy as explained in this section
Alternate Login for Admins and Specified Users
Looker email/password logins are always disabled for regular users when SAML Auth is enabled. This option allows alternate email-based login via
/login/email for admins and for specified users with the
Turning this option ON is useful as a fallback during SAML Auth setup should SAML config problems occur later, or if you need to support some users who do not have accounts in your SAML directory.
Merge by Email
Merge a first-time SAML login to an existing user account by one or more of the specified methods here. Options are Looker Email/Password, LDAP, and Google.
If you have more than one system in place, you can specify more than one system to merge by in this field. Looker will look up users from the systems listed in the order that they are specified. For example, assume you created some users using Looker Email/Password, then you enabled LDAP, and now you want to use SAML. Looker would merge by Email/Password first and then LDAP.
When a user logs in for the first time via SAML, this option will connect the user into their existing account by finding the account with a matching email address. If there is no existing account for the user, a new user account will be created.
When a user attempts to log into a Looker instance using SAML, Looker opens to the Log In page. Authentication via SAML will happen once the user clicks the Authenticate button:
This is the default behavior if the user doesn’t already have an active Looker session.
If you want your users to log directly into your Looker instance after your IdP has authenticated them, and bypass the Log In page, set Bypass Login Page to On:
The Bypass Login Page feature needs to be enabled by Looker. Please contact your Account Manager or email@example.com to update your license for this feature.
When Bypass Login Page is enabled, the user login sequence is as follows:
The user tries to connect to a Looker URL (for example,
Looker determines whether the user already has an active session enabled.
If the user does have an active session enabled, the user is taken to the requested URL.
If the user does not have an active session enabled, they are redirected to the IdP. The IdP authenticates the user when they successfully log into the IdP. Looker then authenticates the user when the IdP sends the user back to Looker with information indicating that the user is authenticated with the IdP.
If authentication at the IdP was successful, Looker then validates the SAML assertions, accepts authentication, updates user information, and forwards the user to the requested URL, bypassing the Log In page.
If the user is unable to log in to the IdP, or if they are not authorized by the IdP to use Looker, then depending on the IdP, they will either remain on the IdP’s site, or be redirected to the Looker Log In page.
Be sure to verify that all tests are passing before clicking Update Settings. Saving incorrect SAML configuration information could lock yourself and others out of Looker.
Once you are done entering your information, and the tests are all passing, hit Update Settings to save.