Reverse proxy
You can run webPDF behind a reverse proxy (hereafter referred to as "proxy") if you do not want the webPDF server to respond to direct requests.
In this case, the webPDF server will communicate exclusively with the proxy server. Within this context, the proxy server and the webPDF server can use different URL addresses (scheme, host, and protocol). For instance, while the proxy uses port 80 for external requests, the webPDF server can work with 8080 internally and communicate with the proxy solely via this port. This means that the webPDF server will only communicate internally and will not respond to any external requests (potentially blocked by a firewall as well).
Accordingly, some adjustments will need to be made for individual webPDF areas in certain cases when using a proxy server.
SOAP web services
No separate changes are required when using SOAP web services exclusively. These web services will respond exclusively to the proxy server and do not provide any URL information in their responses. In this case, the webPDF server will not need any information regarding the proxy server’s or original request’s settings.
REST web services
When using REST web services, certain endpoints respond with HTTP status codes and URL information. An example would be a "303 See Other" with a reference to a new URL. In this case, the webPDF server would need to know the URL of the original request in order to be able to return a correct response. If the webPDF server is run behind a proxy, however, it will not have the original request from the client, but instead will have the proxy’s request only. This means that the webPDF server will need information regarding the original request or settings that enable it to correctly respond to the request.
Portal
On the portal, URL information regarding the webPDF server is required in order for the portal to work correctly and be able to call web services. In addition, certain REST calls (please refer to the previous paragraph) return URL information that is interpreted and processed further by the portal. The "config.js" file, which is generated and retrieved dynamically by the server, is used to configure the webPDF server on the portal. This JSON file provides information indicating how web services can be called. Accordingly, the webPDF server needs to have information regarding the client’s original request, but if it is running behind a proxy, it will not have this information. This means that either the information must be delivered by the proxy or webPDF must be configured accordingly.
Configuration behind a proxy
There are two ways to run webPDF behind a proxy and pass information regarding the original request to the webPDF server:
- With the header fields from the proxy request passed to the webPDF server
- With the static configuration in the webPDF server’s "server.xml"
For 1)
The proxy can use "X-Forwarded-For" header fields to pass the URL scheme, host, and port information in the request. These header fields enable the proxy to pass information to webPDF specifying the address from which the original request was received. webPDF will then use this information in order to compute the relevant values for the response URLs (e.g., "config.js" or "see other”). Once these settings are available, they will be used to overwrite webPDF’s local settings.
The following header fields are available:
| Usage | Value |
|---|---|
| For the host name | x-forwarded-host |
| For the protocol used (http, https) | x-forwarded-proto |
| For the port used | x-forwarded-port |
To find out more about the settings required in order to send these header fields, please consult the documentation for the proxy server you are using.
The webPDF server will dynamically search for these header fields in proxy requests and replace the computed URL with the elements from the "X-Forwarded-For" header fields. In this case, no changes need to be made to the webPDF configuration.
For 2)
If the proxy does not send any header fields, or if these fields cannot be configured in the proxy, an alternative is to enter a set definition in the webPDF server in "server.xml". For this aim, the "connector" provides the entry "proxy".
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<server xmlns="http://schema.webpdf.de/1.0/configuration/server">
...
<connectors>
<connector enabled="true" address="" port="8080">
<proxy host="..." port="..." scheme="..."/>
</connector>
...
</server>
Enter the values that the proxy server uses towards the outside and that webPDF should use in order to compute its response.
If both header fields and configuration settings are available, the settings in the individual proxy request (i.e., the header fields) will always take precedence.