Table of Contents

       Configure Permissions
       Security Groups
         Global Groups
         Site Groups
         Project Groups
         Guests / Anonymous Users
       Security Roles Reference
         Role / Permissions Matrix
         Administrator Role / Permissions Matrix
         Matrix of Report, Chart, and Grid Permissions
         Developer Roles
       User Accounts
         My Account
         Site Administrator
         Add Users
         Manage Users
         Manage Project Users
         Configure Database Authentication
           Password Reset
         Configure LDAP Authentication
         Configure SAML Authentication
         Configure CAS Single Sign On Authentication (SSO)
         Configure CAS Identity Provider
         LDAP User/Group Synchronization
         Configure Duo Two-Factor Authentication
         Create a netrc file
       Virus Checking
       Test Security Settings by Impersonation
       Premium Resource: Best Practices for Security Scanning


LabKey Server has a group & role-based security model. This means that each user of the system belongs to one or more security groups, and each group has a specific set of permissions (aka "roles") in relation to projects and folders on the system. When you are considering how to secure your LabKey site or project, you need to think about which users belong to which groups, and which groups have access to which projects and folders.

A few best practices:

  • Keep it simple.
  • Take advantage of the permissions management tools in LabKey.
  • Use the rule of least privilege: it is easier to expand access later than restrict it.
  • Prioritize sensible data organization over folder structure.
  • Iterate when necessary.
  • Test after every change.



You may not need to understand every aspect of LabKey security architecture to use it effectively. In general the default security settings are adequate for many needs. However, it's helpful to be familiar with the options so that you understand how users are added, how groups are populated, and how permissions are assigned to groups.

Related Topics

Configure Permissions

The security of a project or folder depends on the permissions that each group has on that resource. The default security settings are designed to meet common security needs, and you may find that they work for you and you don't need to change them. If you do need to change them, you'll need to understand how permissions settings work and what the different roles mean in terms of the kinds of access granted.
Security settings for a Longitudinal Studies provide further refinement on the folder-level permissions covered here, including granular control over access to study datasets within the folder. See Manage Study Security (Dataset-Level Security) for details.


A role is a named set of permissions that defines what members of a group can do. You secure a project or folder by specifying a role for each group defined for that resource. The privileges associated with the role are conferred on each member of the group. Assigning roles to groups is a good way to simplify keeping track of who has access to what resources, since you can manage group membership in one place.

Setting Permissions

To set permissions, you assign a role to a group or individual user.

Note: Before you can grant roles to users, you must first add the users at the site level. When you type into the "Select user or group..." box, it will narrow the pulldown menu to the matching already defined users, but you cannot add a new account from this page.

  • Select (Admin) > Folder > Permissions.
  • Set the scope of the role assignment by selecting the project/folder in the left-hand pane.
  • In the image below the Research Study subfolder is selected.
  • To grant a role, locate it in the Roles column and then select the user or group from the Select user or group... pulldown.
  • Click Save or Save and Finish to record any changes you make to permissions.

Revoke or Change Permissions

Permissions can be revoked by removing role assignments.

  • To revoke assignment to a role, click the x in the user or group box.
  • Here we will revoke the "Author" role for the group "Guests" as it was added by mistake.
  • You can also drag and drop users and groups from one role to another.
  • Dragging and dropping between roles removes the group from the source role and then adds it to the target role. If you want to end up with both roles assigned, you would need to add to the second group instead.

Inherit Permission Settings

You can control whether a folder inherits permission settings, i.e. role assignments, from its immediate parent.

  • Check the checkbox Inherit permissions from parent, as shown below.
  • When permissions are inherited, the permissions UI is grayed out and the folder appears with an asterisk in the hierarchy panel.

Site-Level Roles

A few specific permissions are available at the site level, allowing admins to assign access to certain features to users who are not full administrators. For a listing and details about these roles, see the Security Roles Reference documentation

To configure site-level roles:

  • Select (Admin) > Site > Site Permissions.

Permission Rules

The key things to remember about configuring permissions are:

Permissions are additive. This means that if a user belongs to several groups, they will have the superset of the highest level of permissions granted by all groups they are in.

Additive permissions can get tricky when you are restricting access for one group. Consider whether other groups also have the correct permissions. For example, if you remove permissions for the ProjectX group, but the Users (logged-in-site users) group has read permissions, then Project X team members will also have read permissions when they are signed in.

Folders can inherit permissions. In general, only site admins automatically receive permissions to access newly-created folders. However, default permissions settings have one exception. In the case where the folder admin is not a project or site admin, permissions are inherited from the parent project/folder. This avoids locking the folder creator out of his/her own new folder.

Visibility of parent folders. If a user can read information in a subfolder, but has no read access to the parent, the name of the parent container will still appear on the folder menu and in the breadcrumb path, but it will not be a clickable navigation link.

Related Topics

Security Groups

There are three types of security groups to which users can belong:
  • Global Groups: built-in site-wide groups which have configurable permissions for every project. "Site Users" is a global group.
  • Site Groups: defined by an admin on a site-wide basis and have configurable permissions for every project.
  • Project Groups: defined only for a particular project and the folders beneath it.
All users with accounts on LabKey belong to the Site Users group, a global group, by default. A user can belong to any number of additional project groups.

Related Topics

Global Groups

Global groups are groups that are built into LabKey Server and thus available when configuring permissions for every project. The global groups can be accessed by site admins via (Admin) > Site > Site Groups.

The Site Administrators Group

The Site Administrators group includes all users who have been added as global administrators. Site administrators have access to every resource on the LabKey site, with a few limited special use exceptions. Only users who require these global administrative privileges should be added to the Site Administrators group. A project administrator requires a similarly high level of administrative access, but only to a particular project, and should be part of the Site Users group, described below and then added to the administrators group at the project level only.

All LabKey security begins with the first site administrator, the person who installs and configures LabKey Server, and can add others to the Site Administrators group. Any site admin can also add new site users and add those users to groups. See Site Administrator for more information on the role of the site admin.

The Site Administrators group is implicit in all security settings. There's no option to grant or revoke folder permissions to this group under (Admin) > Folder > Permissions.

Developers Group

The Developers group is a site-level security group intended to include users who should be granted the ability to create server-side scripts and code. Membership in the Developers group itself does not confer any permission or access to resources. By default, the Developer group is granted the Platform Developer which does confer these abilities.

An administrator can revoke the Platform Developer role from this group if desired, in which case the Developers group exists purely as a convenience for assigning other roles throughout the site.

Membership in the Developers site group is managed on the page (Admin) > Site > Site Developers. The same interface is used as for project groups. Learn more about adding and removing users from groups in this topic: Manage Group Membership

Note that you cannot impersonate the Developers group or the Platform Developers role directly. As a workaround, impersonate an individual user who has been added to the Developers group or granted the Platform Developer role respectively.

The Site Users Group

The site-level Users group consists of all users who are logged onto the LabKey system, but are not site admins. You don't need to do anything special to add users to the Site Users group; any users with accounts on your LabKey Server will be part of the Site Users group.

The Site Users group is global, meaning that this group automatically has configurable permissions on every resource on the LabKey site.

The purpose of the Site Users group is to provide a way to grant broad access to a specific resource within a project without having to open permissions for an entire project. Most LabKey users will work in one or a few projects on the site, but not in every project.

For instance, you might want to grant Reader permissions to the Site Users group for a specific subfolder containing public documents (procedures, office hours, emergency contacts) in a project otherwise only visible to a select team. The select team members are all still members of the site users group, meaning the resource will be visible to all users regardless of other permissions or roles.

The Guests/Anonymous Group

Anonymous users, or guests, are any users who access your LabKey site without logging in. The Guests group is a global group whose permissions can be configured for every project and folder. It may be that you want anonymous users to be able to view wiki pages and post questions to a message board, but not to be able to view MS2 data. Or you may want anonymous users to have no permissions whatsoever on your LabKey site. An important part of securing your LabKey site or project is to consider what privileges, if any, guests should have.

Permissions for guests can range from no permissions at all, to read permissions for viewing data, to write permissions for both viewing and contributing data. Guests can never have administrative privileges on a project.

Related Topics

Site Groups

Site Groups allow site admins to define and edit site-wide groups of users. Site groups have no default permissions but are visible to every project and may be assigned project-level permissions as a group.

The server has built-in site groups described here: Global Groups.

Create a Site Group

View current site groups by selecting (Admin) > Site > Site Groups:

To create a new group, enter the name, here "Experimenters" then click Create New Group. You may add users or groups and define permissions now, or manage the group later. Click Done to create your group.

Manage Site Groups

Membership in site groups is managed in the same way as membership in project groups. Learn more in this topic: Manage Group Membership.

Clicking on the group name to view the group information box.

  • Add a single user or group using the pulldown menu.
  • Remove a user from the group by clicking Remove.
  • View an individual's permissions via the Permissions button next to his/her email address.
  • Manage permissions for the group as a whole by clicking the Permissions link at the top of the dialog box.
  • Click Manage Group to add or remove users in bulk as well as send a customized notification message to newly added users.

Grant Project-Level Permissions to a Site Group

To grant project-level permissions to Site Groups (including the built-in groups Guests and Site Users), select (Admin) > Folder > Permissions from the project or folder. Site groups will be listed among those eligible for assignment to each role.

Related Topics

Project Groups

Project groups are groups of users defined only for a particular project and the folders beneath it. You can define any number of groups for a project. To define groups or configure permissions, you must have administrative privileges on that project or folder.

Create a Project Group

View current project groups by selecting (Admin) > Folder > Permissions and clicking the Project Groups tab. To create a new group, type the name into the box and click Create New Group.

Manage Group Membership

Add Users to Groups

When you create a new group, or click the name of an existing group in the permissions UI, you will open a popup window for managing group information.

In the popup window, you can use the pulldown to add project or site users to your new group right away, or you can simply click Done to create the empty group. Your new group will be available for granting roles and can be impersonated even before adding actual users.

Later, return to the project group list, click the group name to reopen the group information popup. You can now use the pulldown to add members or other groups to the group. Once you've added users, new options are available.

Remove Users from Groups

To remove a user from a group, open the group by clicking the group name in the permissions UI. In the popup, click Remove for the user to remove.

You can also see a full set of permissions for that user by clicking Permissions for the user, or the set for the group by clicking the Permissions link at the top of the popup.

When finished, click Done.

Add Multiple Users

From the permissions UI, click the name of a group to open the information popup, then click Manage Group in the upper right for even more options including bulk addition and removal of users. You can rename the group using the link at the top, and the full history of this group's membership is also shown at the bottom of this page.

To add multiple users, enter each email on it's own line in the Add New Members panel. As you begin to type, autocompletion will show you defined users and groups. By default email will be sent to the new users. Uncheck the box to not send this email. Include an optional message if desired. Click Update Group Membership.

Remove Multiple Users

To remove multiple users, reopen the same page for managing the group. Notice that group members who are already included in subgroups are highlighted with an asterisk. You can use the Select Redundant Members button to select them all at once.

To remove multiple group members, check their boxes in the Remove column. Then click Update Group Membership.


To delete a group, you must first remove all the members. Once the group is empty, you will see a Delete Empty Group button on both the manage page and in the information popup.

Default Project Groups

When you create a new project, you can elect whether to start the security configuration from scratch ("My User Only") or clone the configuration from an existing project. Every new project started from scratch includes a default "Users" group. It is empty when a project is first created, and not granted any permissions by default.

It is common to create an "Administrators" group, either at the site or project level. It's helpful to understand that there is no special status confirmed by creating a group of that name. All permissions must be explicitly assigned to groups. A site administrator can configure a project so that no other user has administrative privileges there. What is important is not whether a user is a member of a project's "Administrators" group, but whether any group that they belong to has the administrator role for a particular resource.

Permissions are configured individually for every individual project and folder. Granting a user administrative privileges on one project does not grant them on any other project. Folders may or may not inherit permissions from their parent folder or project.

Related Topics

Guests / Anonymous Users

Guests are any users who access your LabKey site without logging in. In other words, they are anonymous users. The Guests group is a global group whose permissions can be configured for every project and folder. It may be that you want anonymous users to be able to view wiki pages and post questions to a message board, but not to be able to view MS2 data. Or you may want anonymous users to have no permissions whatsoever on your LabKey site. An important part of securing your LabKey site or project is to consider what privileges, if any, anonymous users should have.

Permissions for anonymous users can range from no permissions at all, to read permissions for viewing data, to write permissions for both viewing and contributing data. Anonymous users can never have administrative privileges on a project or folder.

Granting Access to Guest Users

You can choose to grant or deny access to guest users for any given project or folder.

To change permissions for guest users, follow these steps:

  • Go to (Admin) > Folder > Permissions and confirm the desired project/folder is selected.
  • Add the guest group to the desired roles. For example, if you want to allow guests to read but not edit, then add the Guests group in the Reader section. For more information on the available permissions settings, see Configure Permissions.
  • Click Save and Finish.

Default Settings

Guest Access to the Home Project

By default guests have read access to your Home project page, as well as to any new folders added beneath it. You can easily change this by editing folder permissions to uncheck the "inherit permissions from parent" box and removing the guests group from the reader role. To ensure that guest users cannot view your LabKey Server site at all, simply removing the group from the reader role at the "home" project level.

Guest Access to New Projects

New projects by default are not visible to guest users, nor are folders created within them. You must explicitly change permissions for the Guests group if you wish them to be able to view any or all of a new project.

Related Topics

Security Roles Reference

A role is a named set of permissions that defines what a user (or group of users) can do. This topic provides details about site and project/folder scoped roles.

Site Scoped Roles

These roles apply across the entire site. Learn about setting them here.

Site Administrator: The site administrator role is the most powerful role in LabKey Server. They control the user accounts, configure security settings, assign roles to users and groups, create and delete folders, etc. Site administrators are automatically granted nearly every permission in every project or folder on the server. There are some specialized permissions not automatically granted to site admins, such as adjudicator permissions and permission to view PHI data. See Site Administrator.

Application Administrator: This role is used for administrators who should have permissions above Project Administrators but below Site Administrators. It conveys permissions that are similar to Site Administrator, but excludes activities that are "operational" in nature. For example, they can manage the site, but can't change file/pipeline roots or configure the database connections. For details, see Administrator Role / Permissions Matrix

Troubleshooter: Troubleshooters may view administration settings but may not change them. Troubleshooters see an abbreviated admin menu that allows them to access the Admin Console. Most of the diagnostic links on the Admin Console, including the Audit Log, are available to Troubleshooters.

See User and Group Details: Allows non-administrators to see email addresses and contact information of other users as well as information about security groups.

See Email Addresses: Allows selected non-administrators to see email addresses.

See Audit Log Events: Only admins and selected non-administrators granted this role may view audit log events and queries.

Email Non-Users: Allows sending email to addresses that are not associated with a LabKey Server user account.

See Absolute File Paths: Allows users to see absolute file paths.

Use SendMessage API: Allows users to use the send message API. This API can be used to author code which sends emails to users (and potentially non-users) of the system.

Platform Developer: The platform developer role allows admins to grant developer access to trusted individuals who can then write and deploy code outside the LabKey security framework. By default, the Developer group is granted this role on a site-wide basis. For more information, see this topic: Platform Developer Role

Trusted Analyst: (Premium Feature) This role grants the ability to write code that runs on the server in a sandbox as well as the ability to share that code for use by other users under their own userIDs. For set up details, see Developer Roles.

Analyst: (Premium Feature) This role grants the ability to write code that runs on the server, but not the ability to share that code for use by other users.

Launch and use RStudio Server: (Premium Feature) Allows the user to use a configured RStudio Server.

Project and Folder Scoped Roles

Users and groups can be assigned the following roles at the project or folder level. Learn about setting them here.

Project and Folder Administrator: Similar to site admins, project and folder administrators also have broad permissions, but only within a given project or folder. Within their project or folder scope, these admins create and delete subfolders, add web parts, create and edit sample sets and assay designs, configure security settings, and manage other project and study resources.

When a new subfolder is created within a project, existing project admin users and groups will be granted the folder admin role in the new folder. The admin creating the folder can adjust that access as needed. Once a folder is created and permissions configured, any subsequent new project admin users or groups will not be automatically be granted folder admin to the existing folder.

Editor: The editor role lets the user add new information and modify some existing information. For example, an editor can add and modify wiki pages, post new messages to a message board and edit existing messages, post new issues to an issue tracker and edit existing issues, view and manage MS2 runs, and so on.

Author: The author role lets you create new data and in some cases edit or delete your own data. An author may read the work of others but may not modify it. For example, a user assigned the author role can edit or delete their own message board posts, but not anyone else's posts. The ability for authors to edit and delete their own data is supported for a limited set of data types, currently Wikis, Issues, and Message Boards. It is not supported for other data types such as Datasets, Lists, etc.

Reader: The reader role lets you read text and data, but generally you can't modify it.

Message Board Contributor: This role lets you participate as an "Author" in message board conversations and Object-Level Discussions. You cannot start new discussions, but can post comments on existing discussions. You can also edit or delete your own comments on message boards.

Shared View Editor: This role lets the user create and edit shared views without having broader Editor access. Shared View Editor includes Reader access, and applies to all available queries or datasets.

QC Analyst: (Premium Feature) - Perform QC related tasks, such as assigning QC states in datasets and assays. This role does not allow the user to manage QC configurations, which is available only to administrators. For set up details, see Assay QC States - Admin Guide.

Submitter: The submitter role lets you insert new records, but not view or change other records.

Assay Designer: Assay designers may perform several actions related to creating assay designs.

Specimen Coordinator: Specimen Coordinators may perform a number of management tasks related to specimens. A Specimen Coordinator must also be given the Reader role. This role is available only in a project or folder containing a study or with a study in a descendant folder.

Specimen Requester: Specimen Requesters may request specimen vials. This role is available only in a project or folder containing a study or with a study in a descendant folder.

Developer: Developer is not a role, but a site-level group that users can be assigned to. Developers can create executable code on the server, for example, adding <script> tags to wiki pages and adding R reports and JavaScript reports to data grids. They cannot define new SQL queries using the schema browser. For details see Global Groups.

PHI-related Roles: (Premium Feature) - For details see Compliance: Security Roles. Note that these roles are not automatically granted to administrators.

Related Topics

Role / Permissions Matrix

The table below shows the individual permissions that make up the common roles assigned in LabKey. There are other roles available for specific use cases; details follow the table.

Roles are listed as columns, individual permissions are listed as rows. A dot indicates that the individual permission is included in the given role. For example, when you set "Update" as the required permission, you are making the web part visible only to Administrators and Editors.

Use this table when deciding the permissions required to view a web part.

PermissionsAdministrators *EditorAuthorReaderSubmitterMessage Board ContributorShared View EditorAssay DesignerSpecimen CoordinatorSpecimen Requester
Read Some (read resources that you own)    
Participate in Message Board Discussions      
Start New Discussions       
Read/Respond on Secure Message Board        
Edit Shared Views       
Administrate *         
Export Folder         
Design Assays        
Design Lists        
Share Participant Groups        
Share Report       
Edit Shared Report       
Manage Study        
Manage Notifications        
Edit Specimen Data       
Lock Specimens        
Manage New Request Form        
Manage Request Statuses        
Manage Specimen Actors        
Manage Specimen Display Settings        
Manage Specimen Request and Tracking Settings        
Manage Specimen Request Default Requirements        
Manage Specimen Requests        
Request Specimens       
Set Specimen Comments        

* See the Administrator Permissions Matrix

Additional Site-level Roles

These roles are granted at the site level and grant permissions typically reserved for administrators.

Troubleshooter:  The troubleshooter role grants a user Read-only access to the admin console, including the audit log.

See Email Addresses:  This role grants the to see user email addresses; a permission typically reserved for Administrators.

See Audit Log Events: This role grants the ability to see audit log events; a permission typically reserved for Administrators.

Email Non-Users: This role grants the ability to email non-users; a permission typically reserved for Administrators.

See Absolute File Paths: This role grants the ability to see absolute file paths; a permission typically reserved for Administrators.

Use SendMessage API: This role grants the ability to use the send message API; a permission typically reserved for Administrators.

Platform Developer: This role grants the ability to write and deploy code outside the LabKey security framework. Use caution when granting this role.

Trusted Analyst: (Premium Feature) This role grants the ability to write code in a sandboxed environment and share it with other users.

Analyst: (Premium Feature) This role grants the ability to write code in a sandboxed environment, but not to share it with other users.

Related Topics

Administrator Role / Permissions Matrix

The following tables describe the administrative activities available for the following roles:

  • Site Administrator
  • Application Administrator
  • Troubleshooter

To assign these roles go to > Site > Site Permissions.

The first three tables describe the options available via the > Site > Admin Console, on the Settings tab. The last table describes various user- and project-related activities.

Table Legend

  • all: the Administrator has complete control over all of the setting options.
  • read-only: the Administrator can see the settings, but not change them.
  • none: the Administrator cannot see or change the settings.

Admin Console Section: Configuration

Action Site Admin  Application Admin  Troubleshooter 
ANALYTICS SETTINGSallread-onlyread-only
FOLDER TYPESallallnone
LOOK AND FEEL SETTINGSallread all, change all except System Email Address and Custom Loginread-only
MASCOT SERVERallnonenone
SHORT URLSallallnone
SITE SETTINGSallread-onlyread-only
SYSTEM MAINTENANCEallread-onlyread-only
VIEWS AND SCRIPTINGallread-onlyread-only

Admin Console Section: Management

Action Site Admin  Application Admin  Troubleshooter
AUDIT LOGallallread-only
FULL-TEXT SEARCHallread-onlyread-only

Admin Console Section: Diagnostics

Action Site Admin  Application Admin  Troubleshooter
DATA SOURCESallread-onlyread-only
DUMP HEAPallallread-only
ENVIRONMENT VARIABLESallread-onlyread-only
MEMORY USAGEallallread-only
RUNNING THREADSallallread-only
SQL SCRIPTSallnonenone
SYSTEM PROPERTIESallread-onlyread-only
VIEW ALL SITE ERRORSallallread-only

User and Project/Folder Management

ActionSite AdminApplication AdminProject/Folder AdminNon Admin User Notes
Create new, delete existing, and activate/de-activate usersyesyes (see note)nonoApplication Admins are not allowed to delete or deactivate a Site Admin.
See user details, change password, view permissions, see history gridyesyes (see note)yes (see note)only for themselvesApplication Admins are not allowed to reset the password of a Site Admin.

Project/Folder Admins cannot change passwords.

Edit user details, change user email addressyesyes (see note)nonoApplication Admins are not allowed to edit details or change the email address of a Site Admin.
Update set of Site Admins and Site Developersyesnonono 
Update set of Application Adminsyesyes (see note)nonoThe current user receives a confirmation message when trying to remove themselves from the Application Admin role.
Update Site Groups (create, delete, update members, rename, export members)yesyes (see note)nonoApplication Admins cannot update group memberships for Site Admins or Developers.
Update Site Permissionsyesyesnono 
Impersonate users, roles, and groupsyesyes (see note)yes (see note)no

Application Admins cannot gain Site Admin permissions by impersonating a Site Admin.

Project Admins can only impersonate users in their project.

Create and delete projectsyesyes (see note)nonoApplication Admins cannot set a custom file root for the project on the last step of the project creation wizard.
Create and delete project subfoldersyesyesyesno 
Update Project Settingsyesyes (see note)yes (see note)noOnly Site Admins can set the file root to a custom path.

Related Topics

Matrix of Report, Chart, and Grid Permissions

The following table lists the minimum role required to perform some activity with reports, charts, and grids. For example, to create an attachment, the minimum role required is Author. In general, with "Reader" access to a given folder or dataset, you can create visualizations to help you better understand the data--i.e. check for outliers, confirm a conclusion suggested by another--but you cannot share your visualizations or change the underlying data. To create any sharable report or grid view, such as for collaborative work toward publication of results based on that data, "Author" permission would be required.

General Guidelines

  • Guests: Can experiment with LabKey features (time charts, participant reports, etc) but cannot save any reports/report settings.
  • Readers: Can save reports but not share them.
  • Authors: Can save and share reports (not requiring code).
  • Developers: Extends permission of role to reports requiring code.
  • Admin: Same as editor permissions.
 CreateSaveUpdate (owned by me)Delete (owned by me)Share with others (mine)Share with others in child foldersUpdate (shared by others)Update properties (shared by others)Delete (shared by others)Change sharing (shared by others)
AttachmentAuthorAuthorAuthorAuthorAuthor EditorEditorEditorEditor
Server file attachmentSite AdminSite AdminSite AdminSite AdminSite AdminSite AdminSite AdminSite AdminSite AdminSite Admin
CrosstabReaderReader (non-guest)Reader (non-guest)Reader (non-guest)AuthorProject AdminEditorEditorEditorEditor
Custom ReportReaderReader (non-guest)Reader (non-guest)Reader (non-guest)AuthorProject AdminEditorEditorEditorEditor
Participant ReportReaderReader (non-guest)Reader (non-guest)Reader (non-guest)AuthorProject AdminEditorEditorEditorEditor
Time ChartReaderReader (non-guest)Reader (non-guest)Reader (non-guest)AuthorProject AdminEditorEditorEditorEditor
Query SnapshotAdminAdminAdminAdminAdmin AdminAdminAdmin 
JavascriptDeveloper + AuthorDeveloper + AuthorDeveloper + AuthorDeveloper + AuthorDeveloper + AuthorDeveloper + Project AdminDeveloper + EditorEditorEditorEditor
RDeveloper + AuthorDeveloper + AuthorDeveloper + AuthorDeveloper + AuthorDeveloper + AuthorDeveloper + Project AdminDeveloper + EditorEditorEditorEditor

Related Topics

Developer Roles

Developers can write and deploy code on LabKey Server. This topic describes the roles that can be granted to developers.

Platform Developer

The Platform Developer role allows admins to grant developer access to trusted individuals who can then write and deploy code outside the LabKey security framework. By default, the Developer group is granted this role on a site-wide basis. When that code is executed by others, it may run with different permissions than the original developer user had been granted.

The Platform Developer role is very powerful because:
  • Any Platform Developer can write code that changes data and server behavior.
  • This code can be executed by users with very high permissions, such as Site Administators and Full PHI Readers. This means that Platform Developers have lasting and amplified powers that go beyond their limited tenure as composers of code.
Administrators should (1) carefully consider which developers are given the Platform Developer role and (2) have an ongoing testing plan for the code they write. Consider the Trusted Analyst and Analyst roles as an alternative on Premium Editions of LabKey Server.

Grant the Platform Developer Role

To grant the platform developer role, an administrator selects (Admin) > Site > Site Permissions. They can either add the user or group directly to the Platform Developer role, or if the Developers site group is already granted this role (as shown below) they can add the user to that group by clicking the "Developers" box, then adding the user or group there.

Platform Developer Capabilities

The capabilities granted to users with the Platform Developer role include the following. They must also have the Editor role in the folder to use many of these:

  • APIs:
    • View session logs
    • Turn logging on and off
  • Reports:
    • Create script reports, including JavaScript reports
    • Share private reports
    • Create R reports on data grids
  • Views:
    • Customize participant views
    • Access the Developer tab in the plot editor for including custom scripts in visualizations
    • Export chart scripts
  • Schemas and Queries:
    • Create/edit/delete custom queries in folders where they also have the Editor role
    • View raw JDBC metadata
  • JavaScript:
    • Create and edit announcements with JavaScript
    • Create and copy text/HTML documents with JavaScript
    • Create and edit wikis with JavaScript, using <script> and <style> tags
    • Upload HTML files that include JavaScript, using <script> and <style> tags
    • Create tours
  • Developer Tools:
    • More verbose display and logging
    • Developer Links options on the (Admin) menu
    • Use of the mini-profiler
    • etc.

Developer Site Group

One of the built in site groups is "Developer". This is not a role, but membership in this group was used to grant access to developers prior to the introduction of the platform developer role. By default, the Developers site group is granted the platform developer role.

Premium Feature — The Trusted Analyst and Analyst roles are available in all Premium Editions of LabKey Server. Learn more or contact LabKey.

Trusted Analyst

The role Trusted Analyst grants the ability to write code that runs on the server in a sandbox.

Sandboxing is a software management strategy that isolates applications from critical system resources. It provides an extra layer of security to prevent harm from malware or other applications. Note that LabKey does not verify security of a configuration an administrator marks as "sandboxed".

Code written by trusted analysts may be shared with other users and is presumed to be trusted. Admins should assign users to this role with caution as they will have the ability to write scripts that will be run by other users under their own userIds.

To set up the Trusted Analyst role:

  • Set up a sandboxed script engine in a folder.
  • In the same folder, give the Editor role to the desired script/code writers.
  • Go to (Admin) > Site > Site Permissions and give the Trusted Analyst role to the desired script/code writers.

Trusted analysts also have the ability to create/edit/delete custom queries in folders where they also have the Editor role.


The role Analyst grants the ability to write code that runs on the server, but not the ability to share that code for use by other users. For example, an analyst can use RStudio if it is configured, but may not write R scripts that will be run by other users under their own userIDs.

Related Topics

User Accounts

In order to access secured resources, a user must have a user account on the LabKey Server installation and log in with their user name and password. User accounts are managed by a user with administrative privileges – either a site administrator, who has admin privileges across the entire site, or a user who has admin permissions on a given project or folder.


My Account

Users can edit their own contact information when they are logged in by selecting (User) > My Account.

Edit Account Information

You can edit your information, reset your password, and change your email address, if the "self-service email changes" feature is enabled. An administrator may also make these changes for you. Select My Account from the (User) menu.

To change your information, click the Edit button. The display name defaults to your email address. It can be set manually to a name that identifies the user but is not a valid email address to avoid security and spam issues. You cannot change your user name to a name already in use by the server. When all changes are complete, click Done.

Add an Avatar

You can add an avatar image to your account information by clicking Edit, then clicking Browse or Choose File for the Avatar field. The image file you upload (.png or .jpg for example) must be at least 256 pixels wide and tall.

Change Password

To change your password click Change Password. You will be prompted to enter the Old Password (your current one) and the new one you would like, twice. Click Set Password to complete the change.

An administrator may also change the users password, and also has an option to force a reset which will immediately cancel the user's current password and send an email to the user containing a link to the reset password page. When a password is reset by an admin, the user will remain logged in for their current session, but once that session expires, the user must reset their password before they log in again.

Change Email

The ability for users to change their own email address must first be enabled by an administrator. If not available, this button will not be shown.

To change your email address, click Change Email. You cannot use an email address already in use by another account on the server. Once you have changed your email address, verification from the new address is required within 24 hours or the request will time out. When you verify your new email address you will also be required to enter the old email address and password to prevent hijacking of an unattended account.

When all changes are complete, click Done.

Sign In/Out

You'll find the Sign In/Out menu on the (User) menu. Click to sign in or out as required. Sign in with your email address and password.

Session Expiration

If you try to complete a navigation or other action after your session expires, either due to timeout, signing out in another browser window, or server availability interruption, you will see a popup message indicating the reason and inviting you to reload the page to log back in and continue your action.

Related Topics

Site Administrator

The person who installs LabKey Server at their site becomes the first member of the Site Administrators group and has administrative privileges across the entire site. Members of this group can view any project, make administrative changes, and grant permissions to other users and groups. For more information on built in groups, see Global Groups.

Add Other Site Admins

When you add any users to the Site Administrators group, they will have full access to your LabKey site. Most users do not require such broad administrative access to LabKey, and should be added as site users rather than as administrators. Users who require admin access for a particular project can be granted administrative access at the project level only.

  • Go to (Admin) > Site > Site Admins. You'll see the current membership of the group.
  • In the Add New Members text box, enter the email addresses for your new site administrators.
  • Choose whether to send an email and if so, how to customize it.
  • Click Done.

Related Topics

Add Users

Once you've set up LabKey Server, you're ready to start adding new users. There are multiple ways to add new users to your LabKey installation.

Users Authenticated by LDAP and Single Sign On

If your LabKey Server installation has been configured to authenticate users with an LDAP server or CAS single sign on, you don't need to explicitly add user accounts to LabKey Server.

Every user recognized by the LDAP or single sign on servers can log into LabKey using their user name and password. If they are not already a member, any user who logs in will automatically be added to the "Site Users" group, which includes all users who have accounts on the LabKey site.

Users Authenticated by LabKey

If you are not using LDAP or single sign on authentication, then you must explicitly add each new user to the site.

If you are a site administrator, you can add new users to the LabKey site by entering their email addresses on the Site Users page:

  • Select (Admin) > Site > Site Users.
  • Click Add Users.
  • Enter one or more email addresses.
  • Clone permissions from an existing user if appropriate, otherwise individually assign permissions next.
  • Click Done.

If you have administrative privileges on a project or folder, you can add new users to the LabKey site by adding them to a group in that project. Any users added in this way will also be added to the global "Site Users" group if they are not already included there.

If you are not a site administrator but you have administrative privileges on a project, you can add a new user on the permissions page of any project. The user will simultaneously be added to the "Site Users" group.

  • Select (Admin) > Folder > Permissions.
  • Click the Project Groups tab.
  • Create a new project group or add the user's email address to an existing group.
  • Return to the Permissions tab to define the security roles for that group if needed.
  • Click Save and Finish when finished.

When an administrator adds a new user, that user will receive an email containing a link to a LabKey page where they can log into the system. If you are not using LDAP, the new user will be prompted to choose their own password and log in with that password. The user's password is stored in the database in an encrypted format.

Note: If you have not configured an email server for LabKey Server to use to send system emails, you can still add users to the site, but they won't receive an email from the system. You'll see an error indicating that the email could not be sent that includes a link to an HTML version of the email that the system attempted to send. You can copy and send this text to the user directly if you would like them to be able to log into the system.

Related Topics

Manage Users

All users in LabKey must have user accounts at the site level. The site administrator can add and manage registered user accounts via (Admin) > Site > Site Users page.

Site Users

Edit user contact information and view group assignments and folder access for each user in the list.

  • Select (Admin) > Site > Site Users.

  • Deactivate/Re-activate: Control which users are active, i.e. shown in user-selection dropdowns.
  • Delete: Delete a user account. See below for more information about the consequences of this action; you may want to deactivate instead.
  • Add Users: Click to insert users by entering a list of email addresses. Optionally send notification emails. See Add Users for more details.
  • Change User Properties: Manage the set of columns in this table.
  • History: Show the history of changes, additions, deletions to this table.
  • Has Password: Indicates that the user has a password in LabKey's built-in database authentication system.
Project Administrators can manage similar information for project users by going to (Admin) > Folder > Project Users. See Manage Project Users for further information.

Edit User Contact Information

To edit contact information for a user from the site admin table, hover over the row for the user of interest to expose the (Details) link in the first column, as shown in the screencap above, then click it to view editable details.

  • Show Users: Return to the site users table.
  • Edit: Edit contact information.
  • Reset Password: Force the user to change their password by clearing the current password and sending an email to the user with a link to set a new one before they can access the site.
  • Change Email: Edit the email address for the user.
  • Deactivate: Deactivated users will no longer be able to log in, but their information (including group memberships) will be preserved in case they are re-activated at a later time.
  • Delete: Permanently delete the user. This action cannot be undone and you must confirm before continuing by clicking Permanently Delete on the next page. See below for some consequences of deletion; you may want to consider deactivating the user instead.
  • History: Below the user properties you can see the history of logins, impersonations, and other actions for this user.
Users can manage their own contact information when they are logged in, by selecting (User) > My Account from the header of any page.

Customize User Properties

You can add fields to the site users table, change display labels or order of existing fields and also define which fields are required during the user registration process.

  • Select (Admin) > Site > Site Users.
  • Click Change User Properties.
  • To mark a field as required, check the Required box, as shown for "LastName" below.
  • To add a new field, such as "MiddleName", as shown below:
    • Click Add Field (lower left).
    • Enter the Name: MiddleName (no spaces).
    • Leave the default "Text" Data Type selected.
  • Click Save when finished.

Manage Permissions

To view the groups that a given users belongs to and the permissions they currently have for each project and folder on the site, click the [permissions] link next to the user's name on the Site Users page.

If your security needs require that certain users only have access to certain projects, you must still create all users at the site level. Use security groups to control user access to specific projects or folders. Use caution as the built in group "Site: Users" will remain available in all containers for assignment to roles.

Activate/Deactivate Users

The ability to inactivate a user allows you to preserve a user identity within your LabKey Server even after site access has been withdrawn from the user.

When a user is deactivated, they can no longer log in and they no longer appear in drop-down lists that contain users. However, records associated with inactive users still display the users' names. If you instead deleted the user completely, the display name would be replaced with a user ID number.

The Site Users and Project Users pages show only active users by default. Inactive users can be shown as well by clicking Include Inactive Users above the grid.

Delete Users

When a user leaves your group or should no longer have access to your server, before deciding to delete their account, first consider whether that user ID should be deactivated instead. Deletion is permanent and cannot be undone. You will be asked to confirm the intent to delete the user.

Some consequences of deletion include:

  • The user's name is no longer displayed with actions taken or data uploaded by that user.
  • If the user is the recipient of important system notifications, those notifications will no longer be received.
  • If the user defined as owning data reloads (such as of studies or external data), when the user is deleted, these reloads will raise an error.
  • Group membership and permission settings for the deleted user are lost. You cannot 'reactivate' a deleted user to restore this information.
Generally, deactivation is recommended with long time users. The deactivated user can no longer log in or access their account, but account information is retained for audit and admin access.

Related Topics

Manage Project Users

Site administrators can manage users across the site via the Site Users page. Project administrators can similarly manage users within a single project.

Note that user accounts can only be created at the site level. Once a user exists on the site, administrators can manage their access to project and folder resources.

Project Users

A project user is defined as any user who is a member of any group within the project. To add a project user, add the user to a Project Group.

Project admins can view (but not modify) the set of project users, and access each project user's details: profile, user event history, permissions tree within the project, and group events within the project.

  • Select (Admin) > Folder > Project Users.

Project group membership is related to, but not identical with permissions on resources within a project. There may be users who have permissions to a project but are not project users, such as site admins or other users who have permissions because of a site group. Likewise, a project user may not actually have any permissions within a project if the group they belong to has not been granted any permissions.

Impersonate Project Users

Project admins can impersonate project users within the project, allowing them to see the project just as the member sees it. While impersonating, the admin can not navigate to any other project (including the Home project). Impersonation is available at (User) > Impersonation.

Related Topics


User authentication is performed through LabKey Server's core database authentication system by default. Authentication means identifying the user to the server. In contrast, user authorization is handled separately, by an administrator assigning roles to users and groups of users.

With Premium Editions of LabKey Server, other authentication methods including LDAP, SAML and CAS single sign-on protocols, and Duo two-factor authentication can also be configured. Premium Editions also support defining multiple configurations of each external authentication method.

Authentication Dashboard

To open the main authentication dashboard:

  • Select (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Authentication.
  • Global Settings: Use checkboxes to enable either or both option.
  • Configurations: There are two tabs for configurations:
    • Primary: The default primary configuration is Standard database authentication.
    • On servers where additional authentication methods are enabled, you can use the Add New Primary Configuration dropdown.
    • Secondary: Use this tab to enable a secondary authentication method if desired.
  • Login Form Configurations: These configurations make use of LabKey's login page to collect authentication credentials. Standard database authentication uses this method. If additional configuration methods are added, such as LDAP on a Premium Edition server, LabKey will attempt authenticating against each configuration in the order they are listed. You can drag and drop to reorder them.
  • Single Sign On Configurations: Configurations in this section (if any) let LabKey users authenticate against an external service such as a SAML or CAS server. LabKey will render custom logos in the header and on the login page in the order that the configurations are listed. You can drag and drop to reorder them.

Enable Self Signup

Self sign-up allows users to register for new accounts themselves when using database authentication. When the user registers, they provide their own email address and receive an email to choose a password and sign in.

When enabled via the authentication page, users will see a Register button on the login page. Clicking it allows them to enter their email address, verify it, and create a new account.

When self sign-up is enabled, users will need to correctly enter a captcha sequence of characters before registering for an account. This common method of 'proving' users are humans is designed to reduce abuse of the self sign-up system.

Use caution when enabling this if you have enabled sending email to non-users. With the combination of these two features, someone with bad intent could use your server to send unwanted spam to any email address that someone else attempts to 'register'.

Self-Service Email Changes

Administrators can configure the server to allow non-administrator users to change their own email address (if their password is managed by LabKey Server). To allow non-administrator users to edit their own email address, click Enable next to Self-service email changes.

When enabled uses can edit their email address by selecting (User) > My Account. On the user account page, click Change Email.

Multiple Authentication Configurations and Methods

Premium Features — The ability to add other authentication methods and to define multiple configurations of each method is available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

Multiple authentication methods can be configured simultaneously, which provides flexibility, failsafe protections, and a convenient way for different groups to utilize their own authentication systems with LabKey Server. For example, standard database authentication, an LDAP server, and SAML can simultaneously be used.

For each external method of authentication used with Premium Editions of LabKey Server, there can also be multiple distinct configurations defined and selectively enabled. For example, the following server has 5 available configurations, 3 of which are enabled.

When multiple configurations are available, LabKey attempts to authenticate the user in the order configurations are listed on the Primary tab, followed by the Secondary tab. You can rearrange the listing order by dragging and dropping using the six-block handles on the left.

If any one configuration accepts the user credentials, the login is successful. If all enabled configurations reject the user's credentials, the login fails. This means that a user can successfully authenticate via multiple methods using different credentials. For example, if a user has both an account on a configured LDAP server and a database password then LabKey will accept either. This behavior allows non-disruptive transitions from database to LDAP authentication and gives users an alternate means in case the LDAP server stops responding or its configuration changes.

When migrating users from LDAP to the database authentication method, you can monitor progress using the "Has Password" field on the Site Users table.

Supported Authentication Methods

  • Database Authentication - LabKey Server's built-in database authentication service.
  • LDAP: (Premium Feature starting in version 20.3 (March 2020)) Configure LDAP servers to authenticate users against an organization's directory server.
  • SAML: (Premium Feature) Configure a Security Assertion Mark-up Language authentication method.
  • CAS: (Premium Feature) Authenticate users against an Apereo CAS server.
  • Duo: (Premium Feature) Require users to provide an additional piece of information to be authenticated.

Auto-create Authenticated Users

If one or more remote authentication methods is enabled, you will see an additional checkbox in the Global Settings. By default, new LabKey Server accounts will be automatically created for users who are authenticated by external methods such as LDAP, SAML, or CAS. You can disable it in the global settings by unchecking the box.

If you disable auto creation of authenticated users, be sure to communicate to your users the process they should follow for creating a LabKey account. Otherwise they will be able to authenticate but will not have an actual LabKey account with which to use the server. As one example process, you might require an email request to a central administrator to create accounts. The administrator would create the account, the activation email would invite the user to join the server, and they would be authenticated via the external configuration.

Enable/Disable and Delete Configurations

You cannot disable or delete the basic standard database authentication. When other configurations are available, you can use the toggle available at the top of the settings panel to enable/disable them. Click the (pencil) to edit settings. Click the to delete a configuration.

Related Topics

Configure Database Authentication

Standard database authentication is accomplished using secure storage of each user's credentials in LabKey Server. When a user enters their password to log in, it is compared with the stored credential and access is granted if there is a match and otherwise denied. Administrators may manually create the account using the new user's email address, or enable self-signup. The new user can choose a password and log in securely using that password. The database authentication system stores a representation of each user's credentials in the LabKey database. Specifically, it stores a one-way hash of a salted version of the user-selected password (which increases security) and compares the hashed password with the hash stored in the core.Logins table. Administrators configure requirements for password strength and the password expiration period following the instructions in this topic.

Configure Standard Database Authentication

  • Select (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Authentication.
  • On the Authentication page, find the section Login Form Configurations on the Primary tab.
  • For Standard database authentication, click the (pencil) on the right.
  • In the Configure Database Authentication popup, you have the following options:
  • Password Strength: Require Weak or Strong passwords.
    • The rules for each type are shown.
    • Click the type to use.
  • Password Expiration: Configure how often users must reset their passwords. Options: never, every twelve months, every six months, every three months, every five seconds (for testing).
  • Click Apply.
  • Click Save and Finish.

For details on password configuration options see:

Note: these password configuration options only apply to user accounts authenticated against the LabKey authentication database. The configuration settings chosen here do not effect the configuration of external authentication systems, such as LDAP and CAS single sign on.

Set Default Domain for Login

If you want to offer users the convenience of automatically appending the email domain to their username at log in, you can provide a default domain. For example, if you want to let a user with the email "" log in as simply "justme". You would configure the default domain:

  • Select (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Site Settings.
  • Set the System default domain to the value to append to a username login. In our example, the default domain would be "".

With this configuration, the user can type either "" or "justme" in the Email box at login.

Related Topics


This topic covers options available for configuration of password authentication in the database:

Password Strength

User passwords can be set to either "weak" or "strong" rules.

Weak rules require only that the password:

  • Must be at least 6 non-whitespace characters long
  • Must not match the user's email address
Strong rules require that passwords meet the following criteria:
  • Must be eight or more characters long
  • Must contain characters from at least three of the following character types:
    • lowercase letters (a-z)
    • uppercase letters (A-Z)
    • digits (0-9)
    • symbols (! @ # $ % & / < > = ?)
  • Must not contain a sequence of three or more characters from the user's email address, display name, first name, or last name
  • Must not match any of the user's 10 previously used passwords

Password Expiration

Administrators can also set the password expiration interval. Available expiration intervals are:

  • Never
  • Twelve months
  • Six months
  • Three months
  • Every five seconds - for testing purposes

Password Best Practices for LDAP and SSO Users

For installations that run on LDAP or SSO authentication servers, it is recommended that at least one Site Administrator account be associated with LabKey's internal database authenticator as a failsafe. This will help prevent a situation where all users and administrators become locked out of the server should the external LDAP or SSO system fail or change unexpectedly. If there is a failure of the external authentication system, a Site Administrator can sign in using the failsafe database account and create new database authenticated passwords for the remaining administrators and users, until the external authentication system is restored.

To create a failsafe database-stored password:

  • Select (User) > My Account.
  • Choose Create Password. (This will create a failsafe password in the database.)
  • Enter your password and click Set Password.

After setting up a failsafe password in the database, LabKey Server will continue to authenticate against the external LDAP or SSO system, but it will attempt to authenticate using database authentication if authentication using the external system fails.

Related Topics

Password Reset

This topic covers mechanisms for changing user passwords. A user can change their own password, or an administrator can prompt password changes by setting expiration timeframes or direct prompt.

Self-Initiated Password Reset

Any user can reset their own password from their account page.

  • Select (username) > My Account.
  • Click Change Password.
  • Enter your Old Password and the New Password twice.
  • Click Set Password.

Forgotten Password Reset

If a user has forgotten their password, they can reset it when they are logged out by attempting to log in again.

  • From the logon screen, click Forgot password

You will be prompted for the email address you use on your LabKey Server installation (it may already be populated if you have used "Remember my email address" in the past). Click Reset.

If an active account with that email exists, the user will be sent a secure link to the opportunity to reset their password.

Password Security

You are mailed a secure link to maintain security of your account. Only an email address associated with an existing account on your LabKey Server will be recognized and receive a link for a password reset. This is done to ensure that only you, the true owner of your email account, can reset your password, not just anyone who knows your email address.

If you need to change your email address, learn more in this topic.

Expiration Related Password Reset

If an administrator has configured passwords to expire on some interval, you may periodically be asked to change your password after entering it on the initial sign in page.

If signing on takes you to the change password page:
  • Enter your Old Password and the New Password twice.
  • Click Set Password.

Administrator Prompted Reset

If necessary, an administrator can force a user to change their password.

  • Select (Admin) > Site > Site Users.
  • Click the username for the account of interest. Filter the grid if necessary to find the user.
  • Click Reset Password.
  • This will clear the user's current password, send them an email with a 'reset password' link and require them to choose a new password before logging in. Click OK to confirm.

LabKey Server Account Names and Passwords

The name and password you use to log on to your LabKey Server are not typically the same as the name and password you use to log on to your computer itself. These credentials also do not typically correspond to the name and password that you use to log on to other network resources in your organization.

You can ask your administrator whether your organization has enabled single sign on to make it possible for you to use the same logon credentials on multiple systems.

Related Topics

Configure LDAP Authentication

Premium Feature starting in version 20.3 (March 2020) — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

LabKey Server can use your organization's LDAP (lightweight directory access protocol) server to authenticate users. Using LDAP for authentication has a number of advantages: (1) you don't need to add individual users to LabKey and (2) users don't need to learn a new ID & password (they use their existing network id and password to log into your LabKey site). By default, if you set up a connection to your LDAP server, any user in the LDAP domain can log on to your LabKey application. You can change this default behavior by disabling auto-creating of user accounts. The permissions a user will have are the permissions given to "Logged in users" in each project or folder.

If you are not familiar with your organization's LDAP servers, you will want to recruit the assistance of your network administrator for help in determining the addresses of your LDAP servers and the proper configuration.

LDAP Authentication Process

When a user logs into LabKey with an email address ending in the LDAP domain:

  • LabKey attempts to connect to each LDAP server listed in LDAP Servers, in sequence starting with the first server provided in the list.
  • If a successful connection is made to an LDAP server, LabKey authenticates the user with the credentials provided. After a successful LDAP connection, no further connection attempts are made against the list of LDAP servers, whether or not the user's credentials are accepted or rejected.
  • If the user's credentials are accepted by the LDAP server, the user is logged on to the LabKey Server.
  • If the user's credentials are rejected by the LDAP server, then LabKey authenticates the user via database authentication (provided database authentication is enabled).
  • If the list of LDAP servers is exhausted with no successful connection having been made, then LabKey authenticates the user via database authentication (provided database authentication is enabled).
Note: When configuring LabKey to use an LDAP server you are trusting that the LDAP server is both secure and reliable.

Auto Create Authenticated Users

If a user is authenticated by the LDAP server but does not already have an account on the LabKey Server, the system can create one automatically. This is enabled by default but can be disabled using a checkbox in the global settings of the authentication page

Configure LDAP Authentication

To add a new LDAP configuration, follow these steps:

  • Select (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Authentication.
  • On the Authentication page, on the Primary tab, select Add New Promary Configuration > LDAP...
  • In the popup, configure the fields listed below.
  • After completing the configuration fields, you can click the Test button in the popup to test your LDAP authentication settings. See below.
  • Click Finish to save the configuration.
  • Configuration Status: Click the slider to switch between Enabled and Disabled.
  • Description: Enter a unique descriptive label for this configuration. If you plan to define multiple configurations for this provider, so be sure to use a description that will help you differentiate.
  • LDAP Servers: Specifies the addresses of your organization's LDAP server or servers. You can provide a list of multiple servers separated by semicolons. The general form for the LDAP server address is ldap://, where 389 is the standard port for non-secured LDAP connections. The standard port for secure LDAP (LDAP over SSL) is 636. Note that if you are using secure SSL connections, Java needs to be configured to trust the SSL certificate, which may require adding certificates to the cacerts file. LabKey Server attempts to connect to these servers in the sequence provided here: for details see below.
  • LDAP Domain: For all users signing in with an email from this domain, LabKey will attempt authentication against the LDAP server, and for email accounts from other domains, no LDAP authentication is attempted. Set this to an email domain (e.g., ""), or use '*' to attempt LDAP authentication on all email addresses entered, regardless of domain.
  • LDAP Principal Template: Enter an LDAP principal template that matches the requirements of the configured LDAP server(s). The template supports substitution syntax: include ${email} to substitute the user's full email address and ${uid} to substitute the left part of the user's email address. The default value is ${email}, which is the format required by Microsoft Active Directory. Other LDAP servers require different authentication templates. For example, Sun Directory Server requires a more detailed principal template such as: uid=${uid},ou=people,dc=mydomain,dc=org. Check with your network administrator to learn more about your LDAP server.
  • Use SASL authentication: Check the box to use SASL authentication.
  • Use LDAP Search: The LDAP Search option is rarely needed. It is useful when the LDAP server is configured to authenticate with a user name that is unrelated to the user's email address. Checking this box will add additional options to the popup as described below.

LDAP Security Principal Template

The LDAP security principal template must be set based on the LDAP server's requirements. You can specify two properties in the string that LabKey will substitute before sending to the server:

PropertySubstitution Value
${email}Full email address entered on the login page, for example, ""
${uid}Left part (before the @ symbol) of email address entered on the login page, for example, "myname"

Here are some sample LDAP security principal templates:

ServerSample Security Principal Template
Microsoft Active Directory Server${email}
Sun Directory Serveruid=${uid},ou=people,dc=cpas,dc=org

Note: Different LDAP servers and configurations have different credential requirements for user authentication. Consult the documentation for your LDAP implementation or your network administrator to determine how it authenticates users.

Edit, Enable/Disable, and Delete Configurations

You can define as many LDAP configurations as you require. Be sure to use descriptions that will help you differentiate them. Use the six-block handle on the left to reorder the login form configurations. Enabled configurations will be used in the order they are listed here.

To edit an existing configuration, click the (pencil) icon on the right.

Click the Configuration Status slider in the edit popup to toggle between Enabled and Disabled.

To delete a configuration, click the on the right.

Testing the LDAP Configuration

It is good practice to test your configuration during creation. If you want to reopen the popup to test later, click the (pencil) icon for the configuration to test.

  • From the LDAP Configuration popup, click Test.
  • Enter your LDAP Server URL, the exact security principal to pass to the server (no substitution takes place), and the password.
  • Check the box if you want to use SASL Authentication.
  • Click Test and an LDAP connect will be attempted.

As discussed above, the LDAP security principal must be in the format required by your LDAP server configuration.

If you're unfamiliar with LDAP or your organization's directory services configuration you should consult with your network administrator. You may also want to download an LDAP client browser to view and test your LDAP network servers. The Softerra LDAP Browser is a freeware product that you can use to browse and query your LDAP servers; visit the Softerra download page and click the "LDAP Browser #.#" tab.

LDAP Search Option

If your LDAP system uses an additional mapping layer between email usernames and security principal account names, it is possible to configure LabKey Server to search for these account names prior to authentication.

For example, a username that the LDAP server accepts for authentication might look like 'JDoe', while a user's email address is ''. Once this alternate mode is activated, instead of an LDAP template, you would provide credentials and a source database in which to look up the security principal account name, or alternately a "Lookup field" value to use instead.

To enable:

  • Search DN: Distinguished Name of the LDAP user that will be used to search the LDAP directory.
  • Password: Password for the LDAP user specified as "Search DN".
  • Search base: Search base to use. This could be the root of your directory or the base that contains all of your user accounts.
  • Lookup field: User record field name to use for authenticating via LDAP. The value of this field will be substituted into the principal template to generate a DN for authenticating. In the above image, the principal template uses only this field but you could also use something more complex like "uid=${sAMAccountName},dc=example,dc=com".
  • Search template: Filter to apply during the LDAP search. Valid substitution patterns are ${email} and ${uid}.

  • After entering the appropriate values, you can test the configuration.
  • Click Apply to save the changes.
  • Click Save and Finish to exit the authentication page.

When this is properly configured, when a user attempts to authenticate to the LabKey Server, the server connects to the LDAP server using the "Search DN" and "Password". It will use the search base you specified, and look for any LDAP user account which is associated with the email address provided by the user (applying any filter you provided as the "Search template"). If a matching account is found, the LabKey Server makes a separate authentication attempt using the value of the "Lookup field" from the LDAP entry found and the password provided by user at the login screen.

Related Topics

Configure SAML Authentication

This topic is under construction for the July 2020 release of LabKey Server. For current documentation of this feature, click here.

Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

LabKey Server supports SAML (Security Assertion Markup Language) authentication, acting as a service provider to authenticate against a SAML 2.0 identity provider. You can configure LabKey Server to authenticate against a single SAML identity provider (IdP). LabKey Server supports either plain text or encrypted assertion responses from the SAML identity provider. Note that nameId attribute in the assertion must match the email address in the user's LabKey Server account.

SAML Terminology

  • IdP: Identity Provider. The authenticating SAML server. This may be software (Shibboleth and OpenAM are two open source software IdPs), or hardware (e.g., an F5 BigIp appliance with the APM module). This will be connected to a user store, frequently an LDAP server.
  • SP: Service Provider. The application or server requesting authentication.
  • SAML Request: The request sent to the IdP to attempt to authenticate the user.
  • SAML Response: The response back from the IdP that the user was authenticated. A request contains an assertion about the user. The assertion contains one or more attributes about the user. At very least the nameId attribute is included, which is what identifies the user.

How SAML Authentication Works

From a LabKey sign in page, or next to the Sign In link in the upper right, a user clicks the “SAML” link, which may appear as a logo. LabKey generates a SAML request, and redirects the user’s browser to the identity provider's SSO URL with the request attached. If a given SAML identity provider is configured as the default, the user will bypass the sign in page and go directly to the identity provider.

The identity provider (IdP) presents the user with its authentication challenge. This is typically in the form of a login screen, but more sophisticated systems might use biometrics, authentication dongles, or other two-factor authentication mechanisms. If the IdP verifies the user against its user store, a signed SAML response is generated, and redirects the user’s browser back to LabKey Server with the response attached.

LabKey Server then verifies the signature of the response, decrypts the assertion if it was optionally encrypted, and verifies the email address from the nameId attribute. At this point, the user is considered authenticated with LabKey Server and directed to the server home page (or to whatever page the user was originally attempting to reach).

Auto Create Authenticated Users

todo - possible new default behavior

If a user is authenticated by the SAML server but does not already have an account on the LabKey Server, the system can create one automatically. This is enabled by default but can be disabled using a checkbox in the global settings of the authentication page

Create a New SAML Authentication Configuration

  • Go to (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • In the Configuration section, click Authentication.
  • On the Primary tab of the Configurations panel, select Add New Primary Configuration > SAML...
  • In the popup, configure the properties as described below.
  • Click Finish to save.

You can create multiple SAML configurations on the same server.

Note that the configuration settings make use of the encrypted property store, so in order to configure/use SAML, the MasterEncryptionKey must be set in the labkey.xml file. (If it’s not set, attempting to go to the SAML configuration screen displays an error message, directing the administrator to configure the labkey.xml file.)

Configure the properties for SAML authentication:

  • Configuration Status: Click the slider to toggle between:
    • Enabled
    • Disabled
  • Description: Provide a unique description of this provider.
  • IdP Signing Certificate: Required. Either drag and drop or click to select a pem file.
  • Encryption Certificate (Optional): The encryption certificate for the service provider (SP). Use this field and the SP Private Key field (below) if you want the assertion in the SAML response to be encrypted. These two fields work together: they either must both be set, or neither should be set.
  • SP Private Key (Optional): The private key for the service provider (SP). Use this field and the Encryption Certificate field (above) if you want the assertion in the SAML response to be encrypted. These two fields work together: they either must both be set, or neither should be set.
  • IdP SSO URL (Required): The target IdP (identity provider) URL for SSO authentication, where the SAML identity provider is found.
  • Issuer URL (Optional): The issuer of the service provider SAML metadata. Some IdP configurations require this, some do not. If required, it’s probably the base URL for the LabKey Server instance.
  • NameIdformat (Optional): This is the NameIdformat specified in the SAML request. Options are:
    • Email Address (Default)
    • Transient
    • Unspecified.
  • Force Authorization: If checked, require the user to login again via IdP, even if they are already logged in via an SSO provider.
  • EntityId: The base server entity id is shown here and can be reconfigured if necessary. See note below.
  • Assertion Customer Service (ACS) URL: The ACS URL for this server is show in the UI. It is a combination of the base server EntityID and "saml-validate.view".
  • Default to this SAML Identity Provider: Check the box to redirect the login page directly to this SAML identity provider instead of requiring the user to click on a logo first.
  • Page Header Logo / Login Page Logo: Upload logo images to brand the login UI. See similar logo fields in the CAS documentation: Configure CAS Single Sign On Authentication (SSO).
  • Click Finish in the popup to save.
EntityId / entity_id

Note that the Base Server URL is included in the SAML request as the EntityId / entity_id. To control the Base Server URL, use the "Customize Site page" link in the UI or:

  • Go to (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Site Settings.
  • On the Customize Site page, change the Base Server URL as necessary.
Note that changing this setting will effect links in emails sent by the server, as well as any short URLs you generate. For details see Site Settings.

Edit an Existing SAML Provider

  • Go to (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • In the Configuration section, click Authentication.
  • Click the (pencil) next to the target SAML configuration to edit the configuration.
  • After making changes, click Apply in the popup, then Save and Finish to exit the authentication page.

SAML Functionality Not Currently Supported

  • Metadata generation - LabKey Server supports only static service provider metadata xml.
  • Metadata discovery - LabKey Server does not query an IdP for its metadata, nor does the server respond to requests for its service provider metadata.
If your IdP requires Service Provider XML Metadata, you can generate the XML using a tool such as:
  • Federation participation is not supported.
  • More complex scenarios for combinations of encrypted or signed requests, responses, assertions, and attributes are not supported. For example, signed assertions with individually encrypted attributes.
  • Processing other attributes about the user. For example, sometimes a role or permissions are given in the assertion; LabKey Server ignores these if present.
  • Interaction with an independent service provider is not supported.
  • Single logout (SLO)

Related Topics

Configure CAS Single Sign On Authentication (SSO)

This topic is under construction for the July 2020 release of LabKey Server. For current documentation of this feature, click here.

Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

Central Authentication Service (CAS) is a ticket-based authentication protocol that lets a user sign on to multiple applications while providing their credentials only once to a centralized CAS server (often called a "CAS identify provider"). Enabling CAS authentication lets LabKey Server authenticate users using a CAS identity provider, without users providing their credentials directly to LabKey Server. Learn more in the CAS Protocol Documentation .

You can also configure LabKey Server itself as a CAS Identity Provider, to which other servers can delegate authentication. For details see Configure CAS Identity Provider.

Note that basic HTTP authentication and netrc authentication using usernames are not compatible with SSO authentication such as CAS. API keys can be used as an alternative for authenticating during LabKey API use.

Add/Edit a CAS Single Sign On Configuration

  • Select (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Authentication.
  • In the Configurations section, Primary tab, select Add New Primary Configuration > CAS....
  • In the popup, enter the following:
    • Configuration Status: By default, new configurations are Enabled. Click the slider to change it to Disabled.
    • Description: Enter a unique descriptive label for this configuration. Be sure the description clearly differentiates this configuration from other authentication configurations, especially if you configure multiple CAS configurations. This description will appear in the settings UI and in the audit log every time a user logs in using this configuration.
    • CAS Server URL: Enter a CAS server URL. The URL should start with "https://" and end with "/cas"
    • Default to this CAS Identity Provider: Check the box to make this CAS configuration the default login method.
    • Invoke CAS /logout API on User Logout: Check the box if you want a user logging out of this server to also invoke the /logout action on the CAS identity provider. Otherwise, logout on a server using CAS does not log the user out of the CAS identity provider itself.
    • Page Header Logo & Login Page Logo: Logo branding for the login UI. See examples below.
  • Click Finish.

You will see your new configuration listed under Single Sign On Configurations. If there are multiple configurations, they will be listed in the interface in the order listed here. You can use the six-block handle on the left to drag and drop them to reorder.

Auto Create Authenticated Users

If a user is authenticated by the CAS server but does not already have an account on the LabKey Server, the system can create one automatically. This is enabled by default but can be disabled using a checkbox in the global settings of the authentication page

Single Sign On Logo

Uploaded logos can be displayed on the header area, the login page, or both. This signals to users that single sign on is available. When the logo is clicked, LabKey Server will attempt to authenticate the user against the CAS server.

Edit/Disable/Delete CAS Configurations

On the list of Single Sign On Configurations you will see the CAS configuration(s) you have defined, with an enabled/disabled indicator for each.

  • Use the six-block handle to reorder single signon configurations.
  • Use the to delete a configuration.
  • To edit, click the (pencil) icon.

After making changes in the configuration popup, including switching the Configuration Status slider to Disabled, click Apply to exit the popup and Save and Finish to close the authentication page.

Related Topics

Configure CAS Identity Provider

Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

LabKey Server can be used as a CAS (Central Authentication Service) identity provider. Web servers that support the CAS authentication protocol (including other LabKey deployments) can be configured to delegate authentication to an instance of LabKey Server. The LabKey CAS identify provider implements the /login, /logout, and /p3/serviceValidate CAS APIs. Learn more in the CAS Protocol Documentation .

Initial Set Up

Ensure that the CAS module is deployed on your LabKey Server. Once the CAS module is deployed, the server can function as an SSO identity provider. You do not need to turn on or enable the feature.

However, other servers that wish to utilize the identity service must be configured to use the correct URL; for details see below.

Get the Identity Provider URL

  • Go to (Admin) > Site > Admin Console.
  • Click Settings.
  • Under Premium Features click CAS Identity Provider.
  • Copy the URL shown, or click Copy to Clipboard.

Related Topics

LDAP User/Group Synchronization

Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

LabKey Server can be configured to automatically synchronize with an external LDAP server, so that any user and groups found on the LDAP server are duplicated on LabKey Server. This synchronization is one way: any changes made within LabKey will not be pushed back to the LDAP server.

There are several options to control the synchronization behavior, including:
  • Specifying a synchronization schedule
  • Whether or not LabKey Server creates a user account corresponding to an LDAP user
  • Whether or not LabKey Server creates groups corresponding to LDAP groups
  • Deactivating a LabKey account for users with inactive LDAP accounts
  • Synchronizing based on user and group filters
  • Field mapping between the LDAP and LabKey user information
  • Choosing to enforce or disallow the overwriting of user account information in LabKey
Syncing nested groups is not supported. Groups that are members of other groups must be manually configured in LabKey.

Tomcat Configuration

Note that LDAP synchronization is independent of LDAP authentication and requires a separate connection resource added to the labkey.xml file, described below.

To set up an LDAP synchronization connection:

  • Add a <Resource> to the Tomcat configuration file (labkey.xml).
  • See the example configuration below for a starting template. Replace ADMIN, ADMIN_PASSWORD, and MYLDAP.MYDOMAIN.COM with values appropriate to your organizations LDAP server.
<Resource name="ldap/ConfigFactory" auth="Container"

For details see Installation: SMTP, Encryption, LDAP, and File Roots.

LDAP Sync Settings

Once the LDAP resource has been added, configure the synchronization behavior as follows:

  • Go to (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Premium Features, click LDAP Sync Admin.
The page contains several sections of settings, detailed below.

Connection Settings

To test a connection with an LDAP server, click the Test Connection button.

Search Strings

Use the Search Strings section to control which groups and users are queried on the LDAP server. These settings are optional. Use LDAP syntax to specify search parameters such as "dc=edu" to retrieve .edu addresses.

  • Base Search String
  • Group Search String
  • Group Filter String
  • User Search String
  • User Filter String
An example Group Search string:


You can also control which groups to synchronize using the graphical user interface described below. The string settings made here override any groups chosen in the graphical user interface.

Field Mapping

Use Field Mappings to control how LabKey Server fields are populated with user data. The fields on the left refer to LabKey Server fields in the core.Users table. The fields on the right refer to fields in the LDAP server.

  • Email
  • Display Name
  • First Name
  • Last Name
  • Phone Number
  • UID

Sync Behavior

This section configures how LabKey Server responds to data retrieved from the synchronization.

  • Read userAccountControl attribute to determine if active?: If Yes, then LabKey Server will activate/deactivate users depending on the userAccountControl attribute found in the LDAP server.
  • When a User is Deleted from LDAP: LabKey Server can either deactivate the corresponding user, or delete the user.
  • When a Group is Deleted from LDAP: LabKey Server can either delete the corresponding group, or take no action (the corresponding group remains on LabKey).
  • Group Membership Sync Method: Changes in the LDAP server can either overwrite account changes made in LabKey, or account changes in LabKey can be respected by the sync.
    • Keep in sync with LDAP changes
    • Keep LabKey changes (this allows non-LDAP users to be added to groups within LabKey)
    • Do nothing
  • Set the LabKey user's information, based on LDAP? - If Yes, then overwrite any changes made in LabKey with the email, name, etc. as entered in LDAP.

Choose What to Sync

Choices made here are overwritten by any String Settings you make above.

  • All Users (subject to filter strings above): Sync all users found on the LDAP system.
  • All Users and Groups (subject to filter strings above): Sync all users and groups found on the LDAP system.
  • Sync Only Specific Groups and Their Members: When you select this option, available LDAP groups will be listed on the left. To sync a specific group, copy the group to the right side. Click Reset Group List to clear the selected groups panel.


  • Is Enabled? If enabled, the schedule specified will run. If not enabled, you must sync manually using the Sync Now button below.
  • Sync Frequency (Hours): Specify the cadence of sync refreshes in hours.

Save and Sync Options

  • Save All Settings on Page: Click this button to confirm any changes to the sync behavior.
  • Preview Sync: Provides a popup window showing the results of synchronization. This is a preview only and does not actually make changes on LabKey Server.
  • Sync Now: Perform a manual, unscheduled sync.

Related Topics

Configure Duo Two-Factor Authentication

Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

Two-Factor Authentication is an additional security layer which requires users to perform a second authentication step after a successful primary authentication (username/password). The user is allowed access only after both primary and secondary authentication are successful.

Note that basic username/password authentication is disabled if Duo authentication is enabled. API keys or session-specific keys are required for using the LabKey APIs when Duo is enabled.
LabKey Server supports two-factor authentication through integration with Duo Security. Duo Security provides a variety of secondary authentication methods, including verification codes sent over SMS messages, audio phone calls, and hardware tokens. LabKey Server administrators who wish to take advantage of two-factor authentication will need to open a paid account with Duo Security -- although evaluation and testing can be accomplished with a free trial account. Most of the configuration decisions about the nature of your two-factor authentication service occur within the Duo Security account, not within LabKey Server.

Two-factor authentication requires users to provide an additional piece of information to be authenticated. A user might be required to provide a six-digit verification code (sent to the user's cell phone over SMS) in addition to their username/password combination. The second credential/verification code is asked for after the user has successfully authenticated with LabKey Server's username/password combination. For example, the screenshot below shows the secondary authentication step once a verification passcode that has been sent to his/her cell phone via SMS/text message, voice call, or the Duo mobile application:

Duo Security Setup

To set up two-factor authentication, administrator permissions are required. You first sign up for a Duo Administrator account at the following location:

Next, you specify how Duo will enroll users, and acquire the necessary information to configure LabKey Server:

  • Login to Duo at:
  • On the Duo website, select Applications > New Application.
  • On the Application Type dropdown select "Web SDK" and provide an Application Name of your choice.
  • Click Create Application.
  • Once the Duo Application has been created, you will be provided with an Integration Key, Secret Key, and an API Hostname, which you will use to configure LabKey Server.
  • Under Policy, specify the options for how users will be enrolled in Duo.

Configure Two-Factor Authentication on LabKey Server

  • Select (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Authentication.
  • On the Authentication page, click the Secondary tab in the Configurations panel.
  • Select Add New Secondary Configuration > Duo 2 Factor...
  • Note the Configuration Status is Enabled by default. Click the toggle to disable it.
  • Description: This field is used as the name in the interface. If you will create multiple duo configurations, make sure this description will be unique.
  • Enter the following values which you acquired in the previous step:
    • Integration Key
    • Secret Key
    • API Hostname
    • User Identifier: Select how to match user accounts on LabKey Server to the correct Duo user account. Options:
    • User ID (Default)
    • User Name: To match by username, the Duo user name must exactly match the LabKey Server display name.
    • Full Email Address.
  • Click Finish in the popup to save.

If desired, you can add additional duo configurations. Multiple enabled configurations will be applied in the order they are listed on the Secondary tab. Enable and disable them as needed to control which is in use at a given time.

Edit Configuration

To edit the configuration:

  • Select (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Authentication.
  • Click the Secondary tab.
  • Next to the Duo 2 Factor configuration name you want to edit, click the (pencil} icon to open it.
  • After making any changes needed, click Apply.
  • Click Save and Finish to exit the authentication page.

Enable/Disable Two-Factor Authentication

When you view the Secondary tab you can see which configurations are enabled. To change the status, open the configuration via the (pencil) and click the Configuration Status slider to change between Enabled and Disabled.

Click Apply to save changes, then click Save and Finish to exit the authentication page.

Delete Duo Configuration

To delete a configuration, locate it on the Secondary tab and click the (delete) icon. Click Save and Finish to exit the authentication page.

Troubleshooting Disable

The preferred way to disable two-factor authentication is through the web interface as described above. If problems with network connectivity, Duo configuration, billing status, or other similar issues are preventing two-factor authentication, and thereby effectively preventing all users from logging in, server administrators can disable the Duo integration by adding a line to the labkey.xml or equivalent deployment descriptor in the Tomcat configuration directory:

<Parameter name="org.labkey.authentication.duo.Bypass" value="true" />

After the line is added, restart Tomcat, and then all users will be able to log in without giving a second factor.

Related Topics

Create a netrc file

A netrc file (.netrc or _netrc) is used to hold credentials necessary to login to your LabKey Server and authorize access to data stored there. The netrc file contains configuration and autologin information for the FTP (File Transfer Protocol) client and other programs. It may be used when working with SAS Macros, Transformation Scripts in Java or using the Rlabkey package.

If you receive "unauthorized" error messages when trying to retrieve data from a remote server you should check that your netrc file is configured correctly, you have an entry for that remote machine, and the login credentials are correct. Additional troubleshooting assistance is provided below.

Set Up a netrc File

On a Mac, UNIX, or Linux system the netrc file should be named .netrc (dot netrc) and on Windows it should be named _netrc (underscore netrc). The file should be located in your home directory and the permissions on the file must be set so that you are the only user who can read it, i.e. it is unreadable to everyone else. It should be set to at least Read (400), or Read/Write (600).

To create the netrc on a Windows machine, first create an environment variable called ’HOME’ that is set to your home directory (c:/Users/<User-Name> on Vista or Windows 7) or any directory you want to use.

In that directory, create a text file with the prefix appropriate to your system, either an underscore or dot.

The following three lines must be included in the file. The lines must be separated by either white space (spaces, tabs, or newlines) or commas:

machine <remote-instance-of-labkey-server>
login <user-email>
password <user-password>

One example would be:

password mypassword

Another example would be:

machine login password mypassword

Avoid leaving extra newlines at the end of your netrc file. Some applications may interpret these as missing additional entries or premature EOFs.

Use API Keys

When API Keys are enabled on your server, you can generate a specific token representing your login credentials on that server and use it in the netrc file. The "login" name used is "apikey" (instead of your email address) and the unique API key generated is used as the password. See API Keys for more information and examples.


Port Independence

Note that the netrc file only deals with connections at the machine level and should not include a port or protocol designation, meaning both "" and "" are incorrect.

If you see an error message similar to "Failed connect to; Connection refused", remove the port number from your netrc machine definition.

File Location

An error message similar to "HTTP request was unsuccessful. Status code = 401, Error message = Unauthorized" could indicate an incorrect location for your netrc file. In a typical installation, R will look for libraries in a location like \home\R\win-library. If instead your installation locates libraries in \home\Documents\R\win-library, for example, then the netrc file would need to be placed in \home\Documents instead of the \home directory.

Related Topics

Virus Checking

Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

File uploads, attachments, archives and other content imported through the pipeline or webdav can be scanned for viruses using ClamAV. This topic covers how to configure and use ClamAV antivirus protection.

Configure Antivirus Scanner

  • Select (Admin) > Site > Admin Console.
  • Click Settings.
  • Under Premium Features, click Antivirus.
  • Next to ClamAV Daemon, click Configure.
  • Provide the Endpoint for your ClamAV installation. Your endpoint will differ from this screenshot.
  • The Status message should show the current version and date time. If instead it reads "Connection refused: connect", check that you have provided the correct endpoint and that your service is running.
  • When ready, click Save. Then click Configure Antivirus scanner to return to the configuration page.
  • Select the radio button for ClamAV Daemon, then click Save.

Check Uploads for Viruses

When Antivirus protection is enabled, files uploaded via webdav or included as file attachments will be scanned by the configured provider, such as ClamAV. The process is:

  1. The file is uploaded to a protected "quarantine" location.
  2. The registered antivirus provider is sent a request and scans the file.
  3. If the antivirus provider determines the file is bad, it is deleted from the quarantine location and the user is notified.
  4. If the antivirus scan is successful, meaning no virus is detected, the file is uploaded from the quarantine location to the LabKey file system.
When virus checking is enabled, it is transparent to the users uploading virus-free files.

Virus Reporting

If the antivirus provider determines that the file contains a virus, an alert will be shown to the user either directly as an error message similar to "Unable to save attachments: A virus detected in file: <filename>", or a popup message similar to this:

Developer Notes

If a developer wishes to register and use a different virus checking service, they must do the following:

  • Create a LabKey module. (See Modules: Java.)
  • Create an implementation of org.labkey.api.premium.PremiumService.AntiVirusProvider.
  • Register the implementation using PremiumService.get().registerAntiVirusProvider() when the module starts up.

Related Topics

Test Security Settings by Impersonation

A site or project administrator can test security settings by impersonating a user, group, or role. A project administrator's access to impersonating is limited to the current project; a site administrator can impersonate site wide.

Impersonate a User

Impersonating a user is useful for testing a specific user's permissions or assisting a user having trouble on the site.

  • Select (User) > Impersonate > User. Note that the Impersonate option opens a sub menu listing the options.
  • Select a user from the dropdown and click Impersonate

You are now viewing the site as the user you selected, with only the permissions granted to that user. The username of the user you are impersonating replaces your own username in the header, and you will see a "Stop Impersonating" button.

Impersonate a Group

Impersonating a security group is useful for testing the permissions granted to that group.

  • Select (User) > Impersonate > Group
  • Select a group from the dropdown and click Impersonate

You are now impersonating the selected group, which means you only have the permissions granted to this group. You are still logged in as you, so your display name appears in the header, and you can still edit documents you own (e.g., the reports, messages, wikis, and issues you have created), you are simply temporarily a member of the chosen group.

Is it Possible to Impersonate the "Guests" Group?

Note that the "Guests" group (those users who are not logged into the server) does not appear in the dropdown for impersonating a group. This means you cannot directly impersonate a non-logged in user. But you can see the server through a Guests eyes by logging out of the server yourself. When you log out of the server, you are seeing what the Guests will see. When comparing the experience of logged-in (Users) versus non-logged-in (Guests) users, you can open two different browsers, such as Chrome and Firefox: login in one, but remain logged out in the other.

Impersonate Roles

Impersonating security roles is useful for testing how the system responds to those roles. This is typically used when developing or testing new features, or by administrators who are curious about how features behave.

  • Select (User) > Impersonate > Roles
  • Select one or more roles in the list box and click Impersonate

You are now impersonating the selected role(s), which means you receive only the permissions granted to the role(s). As with impersonating a group, you are still logged in as you, so your display name appears in the menu and you can still edit documents you own.

In some cases you'll want to impersonate multiple roles simultaneously. For example, when testing specialized roles such as Specimen Requester or Assay Designer, you would typically add Reader (or another role that grants read permissions), since the specialized roles don't include read permissions themselves.

When impersonating roles, the menu has an additional option: Adjust Impersonation. This allows you to reopen the role impersonation checkbox list, rather than forcing you to stop impersonating and restart to adjust the roles you are impersonating.

Stop Impersonating

To return to your own account, click the Stop Impersonating button in the header, or select (User) > Stop Impersonating.

Project-Level Impersonation

When any admin impersonates a user from the project users page, the administrator sees the perspective of the impersonated user within the current project. All projects that the impersonated user may have access to outside the current project are invisible while in impersonation mode. For example, when impersonating a project-scoped group, a project administrator who navigates outside the project will have limited permissions (having only the permissions that Guests and All Site Users have). Site admins who want to impersonate a user across the entire site can do so from the site users page or the admin console.

A project impersonator sees all permissions granted to the user's site and project groups. However, a project impersonator never receives authorization from the user's global roles (currently site admin and developer) -- they are always disabled.

Logging of Impersonations

The audit log includes an "Impersonated By" column. This column is typically blank, but when an administrator performs an auditable action while impersonating another user, the administrator's display name appears in the "Impersonated By" column.

When an administrator begins or ends impersonating another user, this action itself is logged under "User Events". See Audit Site Activity for more about auditing.

Premium Resource: Best Practices for Security Scanning

Related Topics