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.
The purpose of this article is to provide 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 a example of 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 should also able to download and schedule content.
- VPs should have almost all privileges, except for a few reserved for just the CEO.
She wants for 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 going through 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, we’ll 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 that is 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’ve 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’ll 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 that 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.
So, 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 that 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’ll create permission sets using the model sets we’ve 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, each set just adding the specific permissions that 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’d reserve for those who A) understand SQL and B) 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 since 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” (since they are creating them it’s logical that they can view them too 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 would look similar to the following:
5. Create Groups
The next step is to create the groups and bucket our users. We’ll create a group for both Standard and Manager in each department, since these will eventually match to the different roles we create later on. 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’ll 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 don’t 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 that 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 would look like:
And the groups would look like:
7. Edit Content Access
We’re close to the end! The next step is to now organize our space access permissions so that 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’ll 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 that we want to have control over 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’ll 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 that 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. And 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’ll imagine there is already an explore being built that has all of the sales information in it. What we’ll do is 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 that only rows accessible to each salesperson is 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 would 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’re done! We’ve finished setting up our content & 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.