Premium Feature — Available in the Professional and Enterprise Editions of LabKey Server. Learn more or contact LabKey.

External applications can dynamically query the data stored in LabKey in order to create reports and perform analyses.

LabKey Server implements the Postgres network wire protocol and emulates the database's responses, allowing supported tools to connect via standard Postgres ODBC and JDBC drivers. Clients connect to LabKey Server, not the backend database, ensuring consistent handling of data and standard LabKey user permissions.

This enables users to continue outside tools they may already be using with data stored in LabKey.

Basic External Analytics Connection Setup

Your server must include the connectors module to support external analytics connections. This module leverages a selected port to pass data from LabKey to an external tool. Across this connection, the user will have access to the data they could also access directly from the UI or via API. The connection does not provide direct access to the database or to any schemas or tables that would not ordinarily be accessible.

To enable connections, follow the instructions below.

  • Select (Admin) > Site > Admin Console.
  • Under Premium Features, click External Analytics Connections.
  • On the page Enable External Analytics Connections, place a check mark next to Allow Connections.
  • By default the server will listen for client requests on port 5435. If desired, you can change the port number within the range: 1 to 65535.
  • The other settings on this page are described in the next section.
  • Click Save.

Secure ODBC Using TLS

Encrypting ODBC connections using Transport Level Security (TLS) is recommended for all deployments and are supported for both cloud and on-premise servers. Secure ODBC connections can piggyback Tomcat's TLS configuration (both certificates and keys), or the server can automatically generate a key pair and self-signed certificate. This topic describes how an administrator configures LabKey Server to accept these secure connections.

To require that ODBC connections are encrypted, you can check the box for Require TLS for encrypted connections. In this section you learn how to configure the LabKey Server deployment. LabKey Server can either get its configuration from Tomcat's HTTPS settings, or use a self-signed certificate. The page also shows the expiration dates for the available certificates.

Using Tomcat's HTTPS Configuration

For details see Use HTTPS with LabKey.

LabKey Server will use the certificateKeyAlias, certificateKeystoreFile, certificateKeystorePassword, and certificateKeystoreType attributes on the <Connector><SSLHostConfig><Certificate> element to configure its TLS connections. It does not support using the certificateFile, certificateChainFile, or certificateKeyFile elements.

If you have specified protocols and/or ciphers on the <Connector> or <Connector><SSLHostConfig> elements, LabKey Server will use them as well. While Tomcat supports both commas or colons as the delimiter for the ciphers list, to make it work with ODBC connections, a colon delimiter must be used in separating cipher suites. For example:

sslProtocol="TLSv1.3" protocols="TLSv1.3"


Using Auto-Generated, Self-Signed Certificate

  • Choose the validity period for newly generated certificates. The server will automatically generate a new certificate when the old one expires.
  • Check the box to Regenerate certificate to force the server to generate a new certificate immediately.
  • Click the (download) link to download the certificate.
  • Click Save.

Configure PostgreSQL Client for Secure Connections

When you configure the client machine where your external tools will run, follow the guidance in the topic for your operating system, making note of the data source name (DSN) requirements for ensuring the connection is secure.

View External Tool Access Settings

Users can review the settings you have configured by selecting (username) > External Tool Access. Values on this page will assist the user in configuring their local connection, including buttons for administrators to download both JDBC drivers for installation and for users to Download Certificate for use with SSL mode.

Additional Topics for External Tools

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all