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.
  • You'll see the Host Name displayed. If necessary, you can check Override Host Name to use another URL.
  • The Require TLS settings on this page are described in the next section.
  • Click Save.

Override Host Name

The Host Name is shown on the External Tool Access pages for users. ODBC connections use this value as the "Server" for the connection. The default value is the base server URL with "-odbc" included, but can be customized as needed. The value provided here should not include a scheme (e.g., http) or port.

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.

Use LabKey's HTTPS Certificate

When Tomcat's HTTPS Certificate is chosen, LabKey Server uses the same settings and certificate for ODBC connections as for other TLS/SSL configuration. Learn more in this topic:

Note that while generally both commas or colons are allowed 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:

server.ssl.ciphers=HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!kRSA:!EDH:!DHE:!DH:!CAMELLIA:!ARIA:!AESCCM:!SHA:!CHACHA20

Use Auto-Generated, Self-Signed Certificate

When Self-signed certificate (managed by LabKey Server) is chosen:

  • 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. This link will be active for the option selected by radio button.
  • 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 in configuring their local connection; tooltips provide additional guidance. Administrators can use links to download drivers for installation and users can download the certificate as needed.

Additional Topics for External Tools

Related Topics

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand allcollapse all