This topic is under construction for the 24.3 (March 2024) 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 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
Service File Customizations and
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:
<SSLHostConfig
sslProtocol="TLSv1.3" protocols="TLSv1.3"
ciphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384:
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384"
>
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
- 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
Related Topics
