— This feature is available with the Professional and Enterprise Editions of LabKey Server. Learn more
or contact LabKey
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.
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.
- 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:
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:
|X-LKPROXY-USERID||RowId for the current user’s account record in LabKey|
|X-LKPROXY-EMAIL||User’s email address|
|X-LKPROXY-SITEROLES||Site-level roles granted to the user|
|X-LKPROXY-APIKEY||Session key linked to the current user’s browser session. This API key is valid until the user logs out explicitly or via a session timeout.|
|X-LKPROXY-CSRF||CSRF token associated with the user’s session. Useful for invoking API actions that involve mutating the server.|
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:
# Configure the path route relative to LabKey's proxy server path
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
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.
Premium Resource Available
Subscribers to premium editions of LabKey Server can try Plotly Dash and a proxy servlet with the example code in this topic:
Learn more about premium editions