Configure a reverse proxy server with ArcGIS Velocity
A reverse proxy server is a computer deployed in a perimeter network, also known as a demilitarized zone (DMZ) or screened subnet, that handles requests from the internet and forwards them to the machines in your internal network. By forwarding requests, the reverse proxy server masks the identity of the machines behind your organization's firewall, which protects internal machines from direct attacks by internet users. You can implement additional security in the reverse proxy server to further protect your internal network from outside users.
You can configure your Velocity site to use your organization's reverse proxy server. This is optional. If your organization does not use a reverse proxy server, or you do not want to configure your Velocity site to use one, you can proceed to configure your site with a portal.
Note:
Do not use ArcGIS Web Adaptor when configuring a reverse proxy for Velocity. Configure the reverse proxy to communicate directly with the Velocity service ports.
Add Velocity to your reverse proxy server
Velocity requires path-based request routing between multiple back-end ports and a layer 7 reverse proxy to route requests between clients and the Velocity services.
The following examples use https://reverseproxy.domain.com/velocity as the service URL and velocity.domain.com as the back-end target host name.
The reverse proxy must route Velocity requests to the following back-end targets. The order of routing rules is important.
| Public route | Back-end target |
|---|---|
/velocity |
Redirect to /velocity/rest/services |
/esri.realtime.core.grpc.GrpcFeed/* |
velocity.domain.com:7145 - gRPC over HTTP/2 with TLS |
/velocity/ws/* |
wss://velocity.domain.com:7146/arcgis/ws/* |
/velocity/styles/* |
https://velocity.domain.com:7143/styles/* |
/velocity/receiver/* |
https://velocity.domain.com:7145/receiver/* |
/velocity/analytic/* |
https://velocity.domain.com:7147/arcgis/* |
/velocity/* |
https://velocity.domain.com:7143/arcgis/* |
List the /velocity/ fallback route last. It routes the Velocity web app, REST API, administration API, OAuth response handling, and other core requests to port 7143. The /velocity context-root redirect is optional, but if configured, evaluate it before the /velocity/ fallback route.
Note:
Velocity includes a gRPC feed type. To use gRPC feeds through the reverse proxy, the configured reverse proxy must support HTTP/2 gRPC proxying over TLS to the Velocity gRPC feed endpoint on port 7145. Internet Information Services (IIS) with Application Request Routing does not support the gRPC feed type in this configuration.
To configure an Apache HTTP Server as a reverse proxy, enable Apache modules mod_ssl, mod_headers, mod_rewrite, mod_proxy, mod_proxy_http, mod_proxy_wstunnel, mod_http2, and mod_proxy_http2. To enable Apache modules, refer to the Apache documentation for the platform-specific configuration locations.
To complete the configuration of an Apache HTTP Server as a reverse proxy, set a combination of ProxyPass and ProxyPassReverse directives and configure SSL settings. Velocity uses HTTPS, so configure the reverse proxy with a certificate that client applications trust. Also configure the reverse proxy to trust the Velocity back-end certificate, or follow your organization's certificate validation requirements.
The following is a configuration template for forwarding client requests:
<VirtualHost *:443>
ServerName reverseproxy.domain.com
SSLEngine on
SSLCertificateFile /path/to/reverseproxy.domain.com.crt
SSLCertificateKeyFile /path/to/reverseproxy.domain.com.key
SSLProxyEngine On
ProxyRequests Off
ProxyPreserveHost On
ProxyAddHeaders On
Protocols h2 http/1.1
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Host expr=%{HTTP_HOST}
RequestHeader set X-Real-IP expr=%{REMOTE_ADDR}
RewriteEngine On
RewriteRule ^/velocity/?$ /velocity/rest/services [R=302,L]
ProxyPass /esri.realtime.core.grpc.GrpcFeed/ h2://velocity.domain.com:7145/esri.realtime.core.grpc.GrpcFeed/ nocanon timeout=3600
ProxyPass /velocity/ws/ wss://velocity.domain.com:7146/arcgis/ws/ nocanon retry=0 timeout=3600
ProxyPassReverse /velocity/ws/ wss://velocity.domain.com:7146/arcgis/ws/
ProxyPass /velocity/styles/ https://velocity.domain.com:7143/styles/ nocanon
ProxyPassReverse /velocity/styles/ https://velocity.domain.com:7143/styles/
ProxyPass /velocity/receiver/ https://velocity.domain.com:7145/receiver/ nocanon
ProxyPassReverse /velocity/receiver/ https://velocity.domain.com:7145/receiver/
ProxyPass /velocity/analytic/ https://velocity.domain.com:7147/arcgis/ nocanon timeout=3600
ProxyPassReverse /velocity/analytic/ https://velocity.domain.com:7147/arcgis/
ProxyPass /velocity/ https://velocity.domain.com:7143/arcgis/ nocanon
ProxyPassReverse /velocity/ https://velocity.domain.com:7143/arcgis/
</VirtualHost>
Most reverse proxy servers have configurable client connection time-outs. When a reverse proxy server reaches the connection time-out, it can disconnect WebSocket connections used by Velocity stream services and gRPC connections used by gRPC feeds. If these connections disconnect at a consistent interval, investigate and increase connection time-outs in the network path.
For more information on how to configure SSL, WebSocket, gRPC, forwarding headers, and proxy directives, refer to the documentation for your reverse proxy server.
Set the WebContextURL property
When users access Velocity through a reverse proxy, set the Velocity WebContextURL property to the URL that users use to access the site. This helps Velocity construct the correct URLs on resources it sends to clients.
Configure the reverse proxy and set WebContextURL before federating Velocity with a portal.
To change the WebContextURL property, complete the following steps:
Sign in to the ArcGIS Velocity Administrator directory at
https://velocity.domain.com:7143/arcgis/adminas a user with administrator privileges.Click System > Properties > Update.
In the Update System Properties dialog box, add or update the
WebContextURLproperty to the existing JSON, substituting your own Velocity URL as seen by users outside your organization's firewall:{ "WebContextURL": "https://reverseproxy.domain.com/velocity" }Click Update Properties.
Note:
This step automatically restarts your Velocity site. Allow the Velocity services to restart before continuing.
Reverse proxy headers and Velocity
Before deploying your reverse proxy server for use with Velocity, configure the reverse proxy headers to preserve the URL and protocol used by clients.
When integrating your reverse proxy with Velocity, configure the reverse proxy to preserve the original host header and send the following headers to the Velocity back-end services:
X-Forwarded-Host=<Fully Qualified Domain Name (FQDN) of reverse proxy server>
X-Forwarded-Proto=https
It is also recommended that the reverse proxy pass the client IP address using the following header:
X-Forwarded-For=<client IP address>
The forwarding header values must correspond to the Velocity WebContextURL property. For example, if you set WebContextURL to https://reverseproxy.domain.com/velocity, the reverse proxy should preserve the original host header and send X-Forwarded-Host=reverseproxy.domain.com and X-Forwarded-Proto=https.
If the forwarding headers do not correspond to the WebContextURL property, Velocity may return the URL of the internal machine where the request was directed, for example, https://velocity.domain.com:7143/arcgis/rest/services instead of https://reverseproxy.domain.com/velocity/rest/services. This is problematic because clients may not be able to access this URL. The client may also gain some knowledge about the internal machine.
When troubleshooting communication between clients and Velocity, confirm that the reverse proxy is preserving the host header and sending the required forwarding headers. The way you configure these headers differs depending on your reverse proxy server implementation.
For more information on how to pass the original host header and configure forwarding headers, refer to the documentation for your reverse proxy server.