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.
Note: in Looker 6.20, Spaces have been renamed to folders.
Introduction
This article provides administrators of Looker instances a guided example of setting up content access controls. 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 (teapot, power tools).
Scenario
The following is an example of a startup with finance, sales, and product teams. The CEO is our only admin, and she wants each team to see only the content that is relevant to them, with the exception that each team's VP should have access to all teams' content. She wants different feature access for standard employees, managers, and VPs.
- Standard employees should be able to view and explore data in their own models.
- 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 desired access controls will involve the following steps:
- Create a Project
- A project is the structural link between a database connection and data models.
- Add Models
- Decide what data will be revealed to which users.
- Create Model Sets
- Group relevant models together.
- Create Permission Sets
- Explicitly define the actions users can take within a model set.
- Create Groups
- Bucket similar users together.
- Create Roles
- Create the connections between model sets, permission sets, and groups.
- Edit Content Access
- Manage which dashboards and Looks users can view via folders.
- Add Data Filters
- Further filter the data that specific users can access within a model.
1. Create a Project
The first thing we need is a project, which is a container for one or more models. Often, a project is already set up for you during the trial/implementation of your Looker instance. If this is the case for your instance, you can skip this step. Otherwise, to set up a new project, go to Develop > 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 to set up version control for the project. For Looker versions up to 7.10, the button is located in the top left of the page, and for Looker versions 7.12 and above, the button is located in the top right of the page. Detailed instructions on setting up version control are on the Setting Up and Testing a Git Connection documentation page.
2. Add Models
A data model is like a customizable portal into the database. Each model may expose different data to users. In our example, our salespeople need different data than our engineers do, so we'll add separate models to expose the appropriate information from the database to each kind of 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 define at least one Explore in each model file; this will allow us to select the model when creating model sets (otherwise, they won't show up in the selection). Just an Explore definition will do for now, and you can see how to use the explore parameter in your model file on the Understanding Model and View Files documentation page.
We have successfully added the models, but we still need to configure them. To configure the models, we'll go back to Develop > Manage LookML Projects, which should now show red text reading "Configuration Required for Use" inline with each model name:
Next to each model, click Configure. We will make sure our project name is correct, along with the connections we will allow this model to use, then save.
After all the models are configured correctly, the red configuration issue messages we saw previously will no longer appear:
Remember that in Looker granting a user the see_lookml or develop permission on one model grants them that permission for all models in that project. 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 that only certain people can query certain data.
For more on permissions, check out our documentation on roles.
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 Admin > Roles 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 when we set up the scenario, we want four tiers of permissions corresponding with the four hierarchical levels in the organization chart, and higher tiers should include the permissions for the tiers 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 Admin > Roles 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 our 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 downloading, scheduling, sharing, creating public looks (which allows sharing of Looks to non-Looker users), and "see_schedules" (because they can create schedules, it's logical that they can also view them in the Admin panel).
Notice that 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 groups for both standard employees and managers 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 and a single model set, and may include one or more groups. Because roles must include a model set, we'll again create roles for both standard employees and managers 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 the 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 the 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 folder access permissions, so each group has access to their own (and only their own) content. Here is the layout of folders and the permission level needed to access each folder:
Access to folders follows the rules of hierarchical inheritance. For more information on how this works, check out our documentation on Access Levels and on Access Control and Permission Management . Following the rules for folder access, we will want to give View access to All Users in the Shared folder. We'll give each group View access to the parent folders in the tree above the folders 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 folder, we won't include that group when giving access. We can give the Manage Access, Edit access level to groups in a folder where we want to control who sees that folder. In our example, we only want the CEO and VPs to have those permissions; everyone else will only have View access to the folders they need.
8. Add Data Access Restrictions with User Attributes
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 our documentation on user attributes). 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 on our User Attributes documentation page.
Filtering Row Data With User Attributes
We will imagine that 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 only each salesperson's own rows are accessible to them. 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 the information from this Help Center article about masking sensitive fields for certain users, to give only 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.