These best practices reflect recommendations shared by a cross-functional team of seasoned Lookers. These insights come from years of experience working with Looker customers from implementation to long-term success. The practices are written to work for most users and situations, but as always use best judgment when implementing.
This article provides administrators of Looker Instances a guided example of setting up content access controls. There are many features that fall under this branch, so this article will provide readers with an understanding of the primary Looker features, to use when implementing content access controls for users. We will walk through the implementation process, starting with a new project, and continuing over models, model sets, permission sets, groups, roles, and user attributes.
First, an analogy to understand the primary Looker features in this context:
A “Project” is like a home.
A “Model” is a room in the home that is filled with specific content.
A “Model Set” is a group of rooms or a single room (bedrooms, kitchen).
A “Permission Set” is an activity checklist, specifying what people can do in a room (eat, play, sleep, ...).
A “Group” is a way to combine people with shared characteristics (adults, kids, guests, ...).
A “Role” is how to give groups of people their activity checklists in different sets of rooms.
A “User Attribute” is a key that opens up special items in the house (alcohol, power tools, ...).
The following is an example of a startup with finance, sales, and product teams. The CEO is our only admin, and she wants each department to only see content relevant to their team (except for the VPs who will have access to all teams’ content). She wants different feature access for VPs, managers, and standard employees.
- Standard employees should be able to view and explore data in their own model.
- Managers should have standard access and also be able to download and schedule content.
- VPs should have almost all privileges, except for a few reserved for just the CEO.
She wants salespeople to be able to view the data for their their own activities, but not be able to view another salesperson’s individual sales numbers. However, sales managers should be able to view every salesperson’s numbers. And finally, there are some finance fields with sensitive information that she wants masked for the standard employees using that model.
The organizational chart is below:
Implementing the above access controls will involve the following steps:
- Create a Project
- A project is the structural link between a database connection and data models.
- Decide what data will be revealed to which users.
- Group relevant models together.
- Explicitly define the actions users can take within a model set.
- Bucket similar users together.
- Create the connections between model sets, permission sets, and groups.
- Manage which Dashboard and Looks users can view via “Spaces.”
- Further filter the data that specific users can access within a model.
1. Create a Project
The first thing we’ll need to do is set up a project (often, this is already done for you during the trial/implementation of your Looker instance. If so, you can skip this step). A project is a container for one or more models. To configure a new Project, go to Developer > Manage LookML Projects and select “New LookML Project.” We’ll give the project a name, specify a connection, and then click “Create Project.”
Upon creating a project, you’ll be brought to the project’s auto-generated LookML model. At this point, you’ll need to use the “Configure Git” button at the top left to set up version control for the project. Detailed instructions on setting up version control are in our documentation.
2. Add Models
A data model is like a customizable portal into the database. Each model may expose different data to users. For example, our salespeople need different data than our engineers, so we’ll add separate models for each, to expose information from the database appropriate for each user.
On the LookML page for our project, we’ll use the “Add Files” button to add new LookML model files with the names of each of our desired models (finance, sales, and product). Make sure to write at least one Explore in each model file (just an Explore definition is fine for now); this will allow us to select the model when creating model sets (otherwise, they won’t show up in the selection).
We have successfully added the models, but we still need to configure them. To configure the models, we’ll go back to the Developer > Manage LookML Projects page, which should now show red “Not Configured” text under the configuration issues:
Next to each model, click “Add Configuration.” We will make sure our project name is correct, along with the connections we will allow this model to use, then save.
After configuring all the models correctly, the configuration issues that were previously red, will now show “OK.”
Remember, in Looker granting the see_lookml or develop permission on one model grants the user that permission for all models in that project. For more on permissions check out our documentation.
Therefore, you should make separate projects if you want to partition permission to view or develop LookML. Otherwise, you should just create a new model. Model permissions are sufficient to ensure only certain people can query certain data.
3. Create Model Sets
Now that the data models for each department have been configured, we’ll add the corresponding model for each department into the model sets we build. To create new model sets, we’ll navigate to the Admin > Roles page and click “New Model Set.” In the end, it would look similar to the screenshot below:
4. Create Permission Sets
Next, we will create permission sets using the model sets we have just made. As mentioned above, we want 4 tiers of permissions corresponding with the 4 hierarchical levels in the organization chart, and higher tiers should include the permissions for the tier below. In our scenario we’ll identify the permission sets as follows:
- CEO → Admin
- VP → Limited Admin
- Manager → Download & Share
- Standard → View & Explore
To create new permission sets, we’ll navigate to the Admin > Roles page and click “New Permission Set.” For each permission tier, we’ll select the appropriate permissions. In general, permission sets should overlap as little as possible, with each set adding only the specific permissions we want the users with this permission set to have. This is because we will be giving some users multiple permission sets, and we want to know exactly what each permission set allows. However, because of the tree structure some overlap is often necessary.
In this example, we want the View & Explore permission set to allow users to view content, ask questions, and save useful tiles. So, we’ll give them permissions associated with “see [content],” “explore,” and “save content,” The notable exceptions here are “see lookml,” which we (may) only want for developers and “see sql,” which we reserve for those who both understand SQL and are trusted to view the database structure. All of these permissions are strictly under the “access data” branch. We are not giving any of the “see” permissions at the bottom of the tree, because they are administrative permissions.
For the Download & Share permission set, we’ll add the permissions associated with download, schedule, share, creating public looks (which allows sharing of looks to non-Looker users), and “see schedules” (because they are creating them, it’s logical that they can also view them in the Admin panel).
Notice in the screenshot below—the only fields that have been selected in both sets are the parent permissions required to select the added child permissions under the “access data” branch.
Finally, for our Limited Admin permission set, we’ll add most of the administrative permissions at the bottom of the tree, excluding the “manage models” and “sudo” privileges that the CEO wants only for herself. That looks like this:
When it’s all done the permission sets will look similar to the following:
5. Create Groups
The next step is to create the groups and bucket our users. We will create a group for both Standard and Manager in each department, because these will eventually match the different roles we later create. VPs will be in their own group and the CEO doesn’t need a group. When completed the Groups page should look like this:
Add Users to Groups
With the groups created, we’ll need to add users into those groups. We will click the “edit” button on the side of each group and add the appropriate users for each one. Remember, because of the way we are structuring permissions, the higher-tier groups may be included in the lower-tier groups. For example, we want the VPs in the Finance group, but we do not want the Sales Managers in the Product group. An efficient way to approach this is to start by adding users to the higher-tier groups (like VPs), so we can add them as a group to the lower tiers.
6. Create Roles
Now that we have our model sets, permission sets, and groups in place, we can put them all together using “Roles.” Every role will have a single permission set, single model set, and may include one or more groups. Because roles must include a model set, we’ll again create a role for both Standard and Manager for each department.
- Standard roles will include the “View & Explore” permission set, plus the corresponding model set. Select the standard and manager groups for that department and VP.
- Manager roles will have the Download & Share permission set, plus the corresponding model set. It should have the manager group for that department and the VP.
- VPs will have the “Limited Admin” permission set, plus the “all” model set and VP Group.
After that’s done the roles will look like:
And the groups will look like:
7. Edit Content Access
We are close to the end! The next step is to organize our space access permissions, so each group has access to their own (and only their own) content. Here is the layout of spaces and the permission level needed to access that space:
Space access follows the rules of hierarchical inheritance. For more information on how this works, check out this User Forums post. Following the rules for space access, we will want to give “View” access to “all users” in the “Shared” space. We’ll give each group “View” access to the parent spaces in the tree above the spaces that the group will have access to. This way, as we traverse down the tree, if we don’t want a group to see a space, we won’t include that group when giving access. We can give “Manage Access/Edit” to groups in a space where we want to control who sees that space. In our example, we only want the CEO and VPs to have those permissions; everyone else will only have “View” access to the spaces they need.
8. Add Data Filters
This section shows methods for preventing specific users from accessing particular rows or columns of data from a model they have access to. Remember, our CEO wants salespeople to be able to view the data for their own individual activities but not others’. Sales managers, however, should be able to view every salesperson’s numbers. To do this, we’ll leverage “User Attributes” and the `sql_always_where` parameter.
Create User Attributes
First, we will create a new user attribute called “access_level” that is hidden from users. This will allow us to define access tiers for the different groups we have (for more information on creating user attributes, check out this documentation). Creating the field should look like this:
While creating the field, we’ll configure 3 levels of access: Basic, Premium, and Full. We’ll assign those levels to the standard, manager, and VP groups, respectively. This is done under the “Group Values” tab in the same section, and looks like this:
Please note that the order of these rules matters, so we want to place the highest access values at the top of the list, to override the lower access values toward the bottom. This behavior is further explained in our documentation.
Filtering Row Data With User Attributes
We will imagine there is already an Explore being built with all the sales information in it. We will check the access level of the user querying the Explore; if the access level is “Basic” (which we’ve given to all our standard salespeople) then we’ll always filter the Explore on the user’s name, so the only rows accessible to each salesperson are his own. If the access level is anything besides “Basic” (premium or full), then the query will not get filtered. By default, we have a user attribute called “name,” which (not surprisingly) is the name of the Looker user. The LookML for the Explore will look like this:
Filtering Column Data With User Attributes
Lastly, there are some PII (Personally identifiable information) columns in the finance model that we want to hide from some of our users as well. To do this, we can use the user attributes we’ve created, along with this User Forum post on masking sensitive fields, to only give our “Full” access level users the ability to see the PII fields.
And we are done! We have finished setting up our content and data access controls and all of our users are free to explore Looker! By doing this we can be assured that they’ll only see the content that we’ve allowed them to see.