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
• 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 used, and consisting of valid characters.
• Target URI: Target URIs are validated as legal URIs.
• 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. Use the Test Link to confirm.

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:

Developers of target web applications must ensure that the pages that are returned include relative (not absolute) URLs, otherwise, subsequent requests will bypass the proxy. The framework may need to be taught to make this adjustment.

For example, Plotly Dash needs the following Python code:

app.config.update({
    # remove the default of '/'
    'routes_pathname_prefix': 'dash/',

    # remove the default of '/'
    'requests_pathname_prefix': 'dash/'
})

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