A reverse proxy server or load balancer is an appliance that is typically deployed within 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. The forwarding of requests on behalf of the reverse proxy server masks the identity of the machines behind your organization's firewall, thus protecting internal machines from being attacked directly by internet users. Additional security functions can be implemented in the reverse proxy server to further protect your internal network from outside users.
If your reverse proxy server or load balancer supports a health check function, you can use the Portal for ArcGIS heath check endpoint to determine whether the portal is available to receive requests. This is useful to quickly determine whether there's a software or hardware failure in the site. For more information, see Health Check.
Caution:
The configuration detailed in this topic must be performed before federating any ArcGIS Server site with your portal. Adding a DNS alias or reverse proxy after an ArcGIS Server site has been federated with your portal is not supported. If you need to change the host name in your organization URL, contact Esri Consulting Services or another trusted consulting partner for guidance.
Unfederating an ArcGIS Server site has several significant consequences and is not easily undone. To learn more, see Administer a federated server.
Load balancer types
Reverse proxies are sometimes referred to as load balancers but typically offer more functionality than just distributing incoming messages across back-end targets. Many reverse proxy server implementations can operate in either capacity described below, depending on the configuration.
Load balancing actions are often differentiated by the layer of the Open Systems Interconnection (OSI) model they operate at. When working to integrate an existing load balancer technology, it is important to identify which type is being implemented, as it affects the overall architecture of the deployment.
Layer 3/4 load balancers are sometimes referred to as network or packet-level load balancers. These load balancers typically do not inspect the incoming traffic and instead route the incoming TCP/UDP packets to the back-end targets. Newer implementations allow for SSL termination on the load balancer, but the client SSL session is typically established with the back-end target server or servers.
Layer 7 load balancers are sometimes referred to as an application or application-aware load balancers. These load balancers inspect the incoming messages and can make routing decisions based on several factors, as well as modify the contents of those messages before proxying them to the back-end target or targets. Layer 7 load balancers using HTTPS will terminate the SSL communication with the client and re-encrypt that traffic before proxying the requests to the back-end HTTPS targets.
Prepare a reverse proxy server or load balancer
Before adding Portal for ArcGIS to your organization's reverse proxy server, you must complete the following:
- Configure HTTPS (HTTP and HTTPS or HTTPS-only) on the reverse proxy server. Portal for ArcGIS uses HTTPS for communication by default. Consult the product documentation for your proxy server to learn how to set up HTTPS.
Note:
Portal for ArcGIS does not support SSL offloading through a reverse proxy server/load balancer. Therefore, if your configuration uses a reverse proxy server, it must forward traffic to either the ArcGIS Web Adaptor or directly to Portal for ArcGIS over HTTPS.
Note:
You must ensure that the reverse proxy server's context name only goes one URL level deep. For example, you can have a reverse proxy URL such as https://proxy.domain.com/enterprise, but you cannot have a reverse proxy URL such as https://proxy.domain.com/myorg/enterprise.
Verify that the proxy server supports gzip encoding and is configured to allow the Accept-Encoding header. This header allows HTTP 1.1 responses to be compressed using gzip encoding. For example, if the header is allowed, a request to load Map Viewer Classic will return a compressed response of approximately 1.4 MB to the browser. If the header is not allowed or ignored, the request will return an uncompressed response of approximately 6.8 MB to the browser. If your network speed is slow, it may take a long time for Map Viewer Classic to load if responses are not compressed. Esri recommends that you allow this header as part of your reverse proxy server configuration.
Layer 3/4 load balancer
The load balancer should listen on the default HTTPS port and pass traffic to either the ArcGIS Web Adaptor or directly to the Portal for ArcGIS machine or machines on port 7443. When terminating client SSL sessions on the Portal for ArcGIS internal web server, ensure that the SSL certificate presented by that web server is valid for both the DNS alias and the FQDN of the machine or machines in the site to avoid certificate trust issues. This can typically be achieved using subject alternative names for the SSL certificate.
Note:
When not using the ArcGIS Web Adaptor, the default context (/arcgis) must be used for the site. When integrating multiple Portal for ArcGIS and ArcGIS Server sites on the same layer 3/4 load balancer, a unique DNS record should be used for each site and Server Name Indication (SNI) used to route traffic to the appropriate back-end targets.
Layer 7 load balancer
In the load balancer configuration, an X-Forwarded-Host header should be set to the host name of the DNS alias of the site. Portal for ArcGIS expects to see this property set in the header sent by the reverse proxy server and will return requests that match the reverse proxy server's URL. If you aren't using ArcGIS Web Adaptor with your portal, confirm that the Host header set by the load balancer matches the host name of the machine where Portal for ArcGIS is installed.
Tip:
You can use the machines endpoint in the Portal Administrator Directory to view the host name of the machine running Portal for ArcGIS.
For example, a request to the ArcGIS Portal Directory (https://dnsalias.domain.com/arcgis/sharing/rest) will be returned to the client as the same URL. If the property is not set, Portal for ArcGIS may return the URL of the internal machine where the request was directed (for example, https://portal.domain.com/arcgis/sharing/rest instead of https://dnsalias.domain.com/arcgis/sharing/rest). This is problematic, as clients will not be able to access this URL (commonly noted as a browser 404 error). Also, this gives the client access to some information about the internal machine.
Along with the X-Forwarded-Host header, your load balancer must be able to direct redirects (HTTP response codes 301 or 302). All Location headers should be rewritten on the load balancer to ensure that the fully qualified domain name (FQDN) and context of the response match the portal's WebContextURL value.
Add a portal
The following sections describe how to add Portal for ArcGIS to your organization's reverse proxy server.
Layer 3/4 load balancer: Add ArcGIS Web Adaptor or Portal for ArcGIS machines to the load balancer configuration
Since the proxying of traffic to the back-end targets will occur over TCP, the machine or machines for each site should be added to the load balancer configuration. If using the ArcGIS Web Adaptor, the back-end targets should point to the port of the web server or servers (typically 443 or 8443) hosting the web adaptor or adaptors. When proxying traffic directly to Portal for ArcGIS, the back-end targets should point to port 7443 on each machine in the site.
Layer 7 load balancer: Add ArcGIS Web Adaptor or Portal for ArcGIS machines to proxy server directives
After configuring ArcGIS Web Adaptor with Portal for ArcGIS, ArcGIS Web Adaptor can be used with your organization's reverse proxy server by adding the components directly to proxy server directives. For example, if you're using Apache as a reverse proxy, you need to add ArcGIS Web Adaptor to the ProxyPass directives in the Apache web server configuration file httpd.conf:
ProxyPass /webadaptorname https://webadaptorhost.domain.com/webadaptorname
ProxyPassReverse /webadaptorname https://webadaptorhost.domain.com/webadaptornameThe ProxyPass directives must match the name designated for ArcGIS Web Adaptor (/webadaptorname in the sample above). When not using the ArcGIS Web Adaptor in front of Portal for ArcGIS, add the following directives where /context is the chosen URL top-level path:
ProxyPass /context https://portal.domain.com:7443/arcgis
ProxyPassReverse /context https://portal.domain.com:7443/arcgisConfigure a portal to use a reverse proxy or load balancer
The following sections describe how to configure your portal to use the reverse proxy server URL and the administrative tasks that must be redone once the URL is configured.
Set the WebContextURL property
The portal's WebContextURL property helps it construct the correct URLs on all resources it sends to the end user. Do the following to change the WebContextURL:
- Open a web browser and sign in to the Portal Administrator Directory as a member of the default Administrator role in your organization. The URL is formatted https://portal.domain.com:7443/arcgis/portaladmin.
- Click System > Properties > Update Properties.
- On the Update System Properties dialog box, insert the following JSON, substituting your own reverse proxy server or DNS alias URL as seen by users outside your organization's firewall.
{ "WebContextURL": "https://dnsalias.domain.com/portal" }Note:
Portal for ArcGIS only supports a single organization URL.
Note:
You cannot use a nonstandard port (that is, a port other than 443) when setting the WebContextURL property.
- Click Update Properties.
Redo administrative tasks
Once you've configured the reverse proxy server with your portal, you'll now access your portal through the reverse proxy server URL instead of the ArcGIS Web Adaptor URL. Anything you access in the portal or the Portal Administrator Directory will return the reverse proxy server URL.
The following administrative tasks should be redone using the reverse proxy server URL:
If you've previously added secured services as items in your portal, you'll need to delete the original items and add them again. This is because the original items use the ArcGIS Web Adaptor URL instead of the reverse proxy server URL. For instructions, see Connect to secure services.
After configuring your reverse proxy server with the portal, you may need to adjust its settings. For example, if operations or requests within your deployment fail with an error indicating the connection timed out, the problem may be that your reverse proxy server's time-out value is too short. To fix this error, consider increasing the time-out value to allow long-running requests, such as federating a server, to complete.