Compliant Access via Session Key

2024-03-28

This topic is under construction for the 24.3 (March 2024) release of LabKey Server. For current documentation of this feature, click here.

To enable programmatic use of data as if "attached" to a given session, an administrator can configure the server to let users obtain a Session Key (or token) once they have logged in via the web UI. This key can be used to authorize client code accessing LabKey Server using one of the LabKey Client APIs. Using any API Key avoids copying and storing your credentials on the client machine. If necessary, users can generate multiple Session Keys for the same session.

As an application example, regulatory compliance may impose stringent data access requirements, such as having the user declare their intended use of the data, provide their IRB number and necessary PHI level, and sign associated terms of use documents every time they log in. This information is logged with each access of the data for later review or audit.

When using a Session Key, access is tied to a given user's current browser session and runs under the current context (e.g., your user, your authorizations and if applicable, your declared terms of use and PHI level, your current impersonation state, etc.) then expires at the end of the session, whether by timeout or explicit logout.

Enable Session Keys

  • Select (Admin) > Site > Admin Console.
  • Under Configuration, click Site Settings.
  • Under Configure API Keys, check Let users create session keys.
  • Click Save.

Obtain and Use a Session Key

Once enabled, the user can log in, providing all the necessary compliance information, then retrieve their unique Session Key from the username > External Tool Access menu:

  • Click Generate Session Key. The Session Key is a long, randomly generated token that is valid for only this single browser session.
  • Click the button to copy it to the clipboard.
    • Important: the key itself will not be shown again and is not available for anyone to retrieve, including administrators. If you lose it, you will need to regenerate a new one.
  • Click Done at the bottom of the page.
You can then paste this key into a script, tying that code's authorization to the browser session where the key was generated. The Session Key can also be used in a .netrc file or via an external client that supports Basic authentication, as shown in API Keys. When using a Session Key within a netrc file, you use the login "apikey." When using a Session Key, the code's actions and access will be logged with your user information and assertions you made at login time.

Example: netrc File

To avoid embedding credentials into your code, you can use a Session Key as a password within a .netrc/_netrc file. When doing so, the username is "apikey" and the password is the entire Session Key including the prefix.

machine localhost
login apikey
password the_long_string_session_apikey

Example: R

For example, if you were accessing data via R, the following shows the usage:

library(Rlabkey)
labkey.setDefaults(apiKey="the_long_string_session_apikey")
labkey.setDefaults(baseUrl="your_base_url_address")

You will then be able to access the data from R until the session associated with that key is terminated, whether via timeout or log out.

Video

Related Topics