This topic is under construction for the 17.1 release of LabKey Server. For current documentation of this feature, click here.
Suppose you are collecting data from multiple labs for a longitudinal study. You want the different teams involved to gather their data and perform quality control steps before the data is integrated into the study. You also want to ensure that the different teams cannot see each other's data until it has been added to the study. This step shows you how to realize these security requirements. You will install a sample workspace that provides a framework of folders and data to experiment with different security configurations.
You configure security by assigning different levels of access to users and groups of users (for a given folder). Different access levels, such as Reader, Author, Editor, etc., allow users to do different things with the data in a given folder. For example, if you assign an individual user Reader level access to a folder, then that user will be able to see, but not change, the data in that folder. These different access/permission levels are called roles
Set Up Security Workspace
The tutorial workspace exists as a folder archive file (a .folder.zip file). It has been preconfigured with subfolders and team resources that you will work with in this tutorial. Below, you will install this preconfigured workspace by creating an empty folder and then importing the folder archive file into that empty folder.
- If you haven't already installed LabKey Server, follow the steps in the topic Install LabKey Server (Quick Install).
- Open a web browser and go to: http://localhost:8080/labkey/project/home/begin.view
- Sign in. You need Project Administrator access to complete these steps. (Which you will have if you installed your own local server. If you are working on a pre-existing server instance, ask the Site Administrator for access.)
- Download the tutorial workspace: SecurityTutorial.folder.zip. Do not unzip.
- Create an empty default folder inside the Home project:
- Navigate to the Home project.
- To create a folder in the Home project: Go to Admin > Folder > Management and click Create Subfolder. Name the subfolder "Security Tutorial". Complete the wizard using the default values. In the next step you will import a folder archive into this empty folder, which will determine its properties.
- Import the folder archive file (SecurityTutorial.folder.zip) into the new folder:
- Go to Admin > Folder > Management > click the Import tab.
- Confirm Local zip archive is selected and click Choose File (or Browse) and select the SecurityTutorial.folder.zip you downloaded.
- Click Import Folder.
- When the folder is finished importing, click Start Page to go to the folder's default tab.
Structure of the Security Workspace
The security workspace contains four folders:
- Security Tutorial -- The main parent folder.
- Lab A - Child folder intended as the private folder for the lab A team, containing data and resources visible only to team A.
- Lab B - Child folder intended as the private folder for the lab B team, containing data and resources visible only to team B.
- Study - Child folder intended as the shared folder visible to all teams.
In the steps that follow we will configure each folder with different access permissions customized for each team.
To see and navigate to these folders in the LabKey Server user interface:
- Hover over the Home link to see the menu of folders inside the Home project.
- Open the folder node Security Tutorial (which you just imported).
- You will see three subfolders inside: Lab A, Lab B, and Study.
- Click a subfolder name to navigate to it.
Configure Permissions for Lab Folders
How do you restrict access to the Lab A folder so that only members of team A can see and change it? The procedure for restricting access has two overarching steps:
- Create a user group corresponding to team A.
- Assign the appropriate roles to this group.
To perform this procedure, first create the groups:
- Navigate to the folder Lab A.
- Go to Admin > Folder > Permissions.
- Notice that the security configuration page is greyed-out. This is because the default security setting, Inherit permissions from parent, is checked. That is, security for Lab A starts out using the settings of its parent folder, Security Tutorial.
- Uncheck Inherit permissions from parent. Notice that the configuration page is activated.
- Click the tab Project Groups. Create the following groups:
- Lab A Group
- Lab B Group
- Study Group
- You don't need to add any users to the groups, just click Done in the popup window.
- Note that these groups are created at the project level, so they will be available in all project subfolders after this point.
Next assign roles to these groups:
- Click the Permissions tab.
- If necessary, select the Lab A folder in the left-side pane.
- Locate the Editor role. This role allows users to see and change items (data, resources, and user interfaces) in the current folder.
- Open the dropdown for the Editor role, select the group Lab A Group to add it.
- Locate the Reader role and remove the All Site Users and Guests groups, if present. If you see a warning when you remove these groups, simply dismiss it.
- Click Save.
- Select the Lab B folder, and repeat the steps on the permissions tab (substituting Lab B for Lab A throughout). Remember to remove all groups from the Reader role.
- Click Save and Finish.
In a real world application you would add individual users (and/or other groups) to Lab A Group and Lab B Group. But this is not necessary to test our permissions configuration. Group and role "impersonation" lets you test security behavior before any actual users are added to the groups.
(Optional) Configure Permissions for Study Folder
In this step we will configure the study folder with the following permissions:
- Lab A and Lab B groups will have Reader access (so those teams can see the integrated data).
- The "Study Group" will have Editor access (intended for those users working directly with the study data).
- Navigate to the folder Study.
- Go to Admin > Folder > Permissions.
- Uncheck Inherit permissions from parent, to activate the configuration panel.
- Locate the Editor role and assign the group Study Group.
- Locate the Reader role and remove All Site Users and Guests, if any are present.
- Locate the Reader role and assign the groups Lab A Group and Lab B Group.
- Click Save and Finish.