One or more Proxy Servlets can be configured by a site administrator to act as reverse proxies to external web applications, such as Plotly Dash. A configured proxy servlet receives HTTP requests from a client such as a web browser, and passes them on to the external web application; HTTP responses are then received and passed back to the client.

The primary benefits of using a proxy servlet are:

• The external web application can be secured behind a firewall. LabKey Server needs access, but clients do not need their own direct access.
• LabKey will securely pass, via HTTP headers, context about the current user to the external web application.This context includes the user's email address, security roles, and an API key that can be used to call LabKey APIs as that user.

Topics

• Set Up for Proxy Servlets
• Configure Proxy Servlets
• Use Proxy Servlets
• Resolve Pathname Prefix
• Delete Servlets

Set Up for Proxy Servlets

To use proxy servlets, you must obtain and deploy the connectors module. Contact your account manager using your support portal or contact LabKey for more information.

To add or edit Proxy Servlet configurations, users must have admin permissions. Users with the "Troubleshooter" site-wide role can see but not edit the configurations.

Configure Proxy Servlets

Administrators configure proxy servlets as follows:

• Select (Admin) > Site > Admin Console.
• Under Premium Features, click Proxy Servlets.
• Enter:
• Proxy Name: Proxy names are case insensitive and must be unique. They are validated for non-blank, not currently in-use, and consisting of valid characters.
• Target URI: Target URIs are validated as legal URIs. The default port for Plotly Dash is 8050, shown below.

• Click Add Proxy.
• An attempt to add an invalid configuration results in an error message above the inputs.

Once added successfully, the proxy servlet configuration appears in the Existing Proxy Servlets grid. The Test Link takes the form:

<serverURL>/<server_context>/_proxy/<proxy_name>/

Click the Test Link to confirm that the connection is successful.

Use Proxy Servlets

All proxy servlets are rooted at LabKey servlet mapping /_proxy/*, so, for example, the dash configuration above on a localhost server would appear at http://localhost:8080/labkey/_proxy/dash/.

This URL can be accessed directly, in which case the web application's output will be shown full screen, with no LabKey frame. Or an iframe can be used to provide display and interactivity within a LabKey page.

The following headers are provided on all requests made to the web application:

Resolve Pathname Prefix

Developers of target web applications must ensure that the pages that are returned include links that resolve through the proxy name, otherwise, subsequent requests will bypass the proxy. One possible symptom of an incorrect path link would be an error like "The resource from [URL] was blocked due to MIME type ("text/html") mismatch (X-Content-Type-Options: nosniff)".

The framework may need to adjust this path to make links resolve correctly as relative to the proxy. For example, a Python script would need the following section:

app.config.update({
    # Configure the path route relative to LabKey's proxy server path
    'routes_pathname_prefix': './',
    'requests_pathname_prefix': './'
})

In older versions of the proxy servlet, you may have needed to explicitly add the name of the proxy servlet ("dash" in this example) to both the routes_pathname_prefix and requests_pathname_prefix. See this example in the documentation archives. If you see a doubled occurrence of the servlet name ("/dash/dash/") you may need to adjust this section of your python script to remove the extra "dash" as shown in the example on this page.

Delete Servlet Configurations

To delete a servlet configuration, click Delete for the row in the Existing Proxy Servlets panel.

Note that you cannot directly edit an existing servlet configuration. To change one; delete it and recreate a new one with the updated target URI.

Related Topics

• Admin Console