Table of Contents

 guest
2025-07-15
   Tutorial: Security
     Step 1: Configure Permissions
     Step 2: Test Security with Impersonation
     Step 3: Audit User Activity
     Step 4: Handle Protected Health Information (PHI)

Tutorial: Security


Securely sharing research data presents a number of major challenges:
  • Different groups and individuals require different levels of access to the data. Some groups should be able to see the data, but not change it. Others should be able to see only the data they have submitted themselves but not the entire pool of available data. Administrators should be able to see and change all of the data. Other cases require more refined permission settings.
  • PHI data (Protected Health Information data) should have special handling, such as mechanisms for anonymizing and obscuring participant ids and exam dates.
  • Administrators should have a way to audit and review all of the activity pertaining to the secured data, so that they can answer questions such as: 'Who has accessed this data, and when?'.
This tutorial shows you how to use LabKey Server to overcome these challenges. In particular this tutorial shows you how to:
  • Assign different permissions and data access to different groups.
  • Test your configuration before adding real users.
  • Audit the activity around your data.
  • Provide randomized data.
As you go through the tutorial, imagine that you are in charge of a large research project, managing multiple teams, each requiring different levels of access to the collected data. You want to ensure that some teams can see and interact with their own data, but not data from other teams. You will need to (1) organize this data in a sensible way and (2) secure the data so that only the right team members can access the right data.

Tutorial Steps:

First Step



Step 1: Configure Permissions


Security Scenario

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:

  1. Create a user group corresponding to team A.
  2. 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.

Start Over | Next Step



Step 2: Test Security with Impersonation


How do you test security configurations before adding any real world users to the system?

LabKey Server uses "impersonation" to solve this problem. You can impersonate a role, a group, or an individual user, shifting perspective on LabKey Server, viewing it as if logged in as a given role, group, or user.

Impersonate Groups

To test the applications behavior, impersonate the groups in question, confirming that each group has access to the appropriate folders.

  • Navigate to the Lab A folder.
  • In the upper right, click your login badge -- this is your user name.
  • Select Impersonate > Group, then select Lab A Group and click Impersonate in the popup.
  • Hover over the folder menu.
  • Notice that the Lab B folder is no longer visible -- while you impersonate, adopting the group A perspective, you don't have the role assignments necessary to see folder B at all.
  • Using the login badge again, stop impersonating and switch to impersonation of group B. Notice that the server will return with the message "User does not have permission to perform this operation", because you are trying to see the Lab A folder while impersonating the Lab B group.
  • Stop impersonating by clicking Stop Impersonating.

Previous Step | Next Step



Step 3: Audit User Activity


Which users have logged on to LabKey Server? What data have they seen, and what operations have they performed?

To get answers to these questions, look at the audit log, a list of user activity that is automatically generated by LabKey Server.

View the Audit Log

  • Go to Admin > Site > Admin Console.
    • If you have less than Project Admin permissions, you will see the message "User does not have permission to perform this operation". (You could either ask your Site Admin for improved permissions, or move to the next step in the tutorial.)
    • If you have Project Admin permissions, you will see a list of user activities.
  • In the Management section, click Audit Log.
  • Click the dropdown and select Project and Folder Events. You will see a list like the following:
  • Click the dropdown again to view other kinds of activity, for example:
    • User Events (which shows who has logged in and when)
    • Group Events (which shows which groups have been assigned which security roles).

Previous Step | Next Step



Step 4: Handle Protected Health Information (PHI)


Data exported from LabKey Server can be protected by:
  • Randomizing participant ids so that the original participant ids are obscured.
  • Shifting date values, such as clinic visits and specimen draw dates. (Note that dates are shifted per participant, leaving their relative relationships as a series intact, thereby retaining much of the scientific value of the data.)
  • Holding back data that has been marked as 'protected'.
In this this step we will export data out of the study, modifying and obscuring it in the ways described above.

Examine Study Data

First look at the data to be exported.

  • Navigate to the Study folder (in Security Tutorial).
  • Click the Clinical and Assay Data tab. This tab shows the individual datasets in the study. There are currently two datasets: "Participants" and "Physical Exam".
  • Click Physical Exam. Notice that the participant ids are 6 digit numbers, starting with "110349". When we export this table, we will randomize these ids, to make it more difficult to identify the subjects of the study.
  • Return to the Clinical and Assay Data tab.
  • Click Participants in the dataset list. Notice the dates in the table are almost all from the last two weeks of April 2008. When we export this table, we will randomly shift these dates, to make it more difficult to identify when subject data was collected.
  • Notice the columns for Country and Gender. We will mark these as "protected" columns, so they are not exported. (As an example, given that there is exactly one male patient from Germany in our sample, he would be easy to identify with only this information.)

Mark Protected Columns

To prepare the data for export, we will mark two columns, "Gender" and "Country" as protected columns making them non-exportable.

  • Click the Manage tab. Click Manage Datasets.
  • Click Participants (the dataset, not the tab) and then Edit Definition.
  • Under Dataset Fields select Gender.
  • Click the Advanced tab and place a checkmark next to Protected.
  • Repeat for the Country field.
  • Click Save.

Set up Alternate Participant IDs

Next we will configure how participant ids are handled on export. We will specify that the ids are randomized using a given text and number pattern.

  • Click the Manage tab.
  • Click Manage Alternate Participant IDs and Aliases.
  • For Prefix, enter "ABC".
  • Click Change Alternate IDs. Click to confirm.
  • Scroll down and click Done.

Export/Publish Anonymized Data

Now we are ready to export this data, using the extra data protections in place.

This procedure will "Publish" the study. That is, a new child folder will automatically be created and selected data from the study will be randomized and copied to the child folder. Once the child folder appears with the exported data, you can configure its security as fits your requirements.

  • If necessary click the Manage tab.
  • Scroll down and click Publish Study.
  • Complete the wizard, selecting all participants, datasets, and timepoints in the study. For fields not mentioned here, enter anything you like.
  • Under Publish Options, check the following options:
    • Use Alternate Participant IDs
    • Shift Participant Dates
    • Remove Protected Columns
    • You could also check Mask Clinic Names which would protect any actual clinic names in the study by replacing them with a generic label "Clinic."
  • Click Finish.
  • Wait for the publishing process to finish.
  • Navigate to the new folder (a child folder under Study).
  • Look at the published datasets Physical Exam and Participants. Notice how the participant ids and dates have been randomized. Notice that the Gender and Country fields have been held back (not been published).

Security for the New Folder

How should you configure the security on this new folder?

The answer depends on your requirements.

  • If you want the general public to see this data, you would add Guests to the Reader role. This allows non-logged-in users to see the folder.
  • If want only members of the study team to have access, you would add Study Group to the Reader role, or a higher role.
For details on the different roles that are available see Security Roles Reference.

Previous Step

What Next?