This topic is under construction for the 17.3 release of LabKey Server. For current documentation of this feature, click here.
Suppose you are collecting data from multiple labs for a longitudinal study. The different teams involved will gather their data and perform quality control steps before the data is integrated into the study. You need to ensure that the different teams cannot see each other's data until it has been added to the study. In this tutorial, 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 is provided as a folder archive file, preconfigured with subfolders and team resources that you will work with in this tutorial. First, install this preconfigured workspace by creating an empty folder and then importing the folder archive file into it. You need Project Administrator access to complete these steps. If you installed your own local server, you will have such access in the home project. If you are working on a shared server, ask your site administrator to provide a location where you can complete this tutorial.
- 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, and navigate to the location where you will complete this tutorial.
- Download the tutorial workspace: SecurityTutorial.folder.zip. Do not unzip.
- Create an empty folder:
- Select (Admin) > Folder > Management and click Create Subfolder.
- Name the folder "Security Tutorial."
- Leave the default "Collaboration" folder type selected and click Next.
- Click Finish on the "Users/Permissions" step. When you import the folder archive, it will set the necessary configuration.
- Import the folder archive file (SecurityTutorial.folder.zip) into the new folder:
- Select (Admin) > Folder > Management and 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 pipeline status shows "COMPLETE", click the folder name to navigate to it.
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:
- Click the Project Menu, then select your project (shown here, the Home project, to see the menu of folders in the folder panel.
- Open the folder node Security Tutorial by clicking the expansion button.
- 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.
- Select (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 by entering the name, then clicking Create New Group.
- 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, navigate the folder tree and 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. Click the X in each entry. If you see a warning when you remove these groups, simply dismiss it.
- Click Save.
- Select the Lab B folder, and repeat the steps:
- Uncheck "Inherit permissions from parent"
- Add "Lab B Group" to the Editor role.
- Remove site user and guest 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.
Configure Permissions for Study Folder
Next 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.
- Select (Admin) > Folder > Permissions.
- Uncheck Inherit permissions from parent, to activate the configuration panel.
- Add "Study Group" to the Editor role.
- Remove any site user and guest groups from the Reader role.
- Add the groups "Lab A Group" and "Lab B Group" to the Reader role.
- Click Save and Finish.