This topic is under construction for the 23.3 (March 2023) release of LabKey Server. For current documentation of this feature, click here.
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 hosted 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 Installation: Tomcat Configuration
and Creating & Installing SSL/TLS Certificates on Tomcat
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:
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 a button to Download Certificate
Additional Topics for External Tools
- Configure ODBC Access from Host Machine: Set up the host machine to use the ODBC connection, including installation of the TLS access certificate for each user.
- Supported ODBC Tools: Configure external tools to use LabKey Server Data.
- Troubleshoot Common Errors