— 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.|
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. Typically, these would be relative URLs that start with the proxy name. The framework may need to be taught to make this adjustment.
For example, Plotly Dash would need the following Python code, assuming the proxy servlet is configured with name "dash":
# remove the default of '/'
# remove the default of '/'
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