Set up a reverse proxy server with ArcGIS Notebook Server—ArcGIS Notebook Server

A reverse proxy server is a computer that is deployed within a perimeter network (also known as a demilitarized zone 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, protecting internal machines from direct attack by internet users. Additional security functions can be implemented in the reverse proxy server to further protect your internal network from outside users.

You can configure your ArcGIS Notebook Server site to use your organization's reverse proxy server. This is optional. If your organization does not use a reverse proxy, or if you don't want to configure your ArcGIS Notebook Server site to use one, you can proceed to configure your site with a portal.

Add ArcGIS Notebook Server to your reverse proxy server

Your organization's reverse proxy server must be configured to communicate with ArcGIS Web Adaptor by adding the corresponding URLs to the proxy directives.

For example, if you're using Apache as a reverse proxy server, you need to add the ArcGIS Web Adaptor URL to the ProxyPass directives in the Apache web server configuration file httpd.conf as follows:

ProxyPass /notebook https://notebookserver.domain.com/notebook
ProxyPassReverse /notebook https://notebookserver.domain.com/notebook

Most reverse proxy servers have a configurable client connection time-out. The websocket connections used by ArcGIS Notebook Server to communicate with the Python kernel will be disconnected when the connection time-out is reached, and a notification will appear within the notebook. If this happens at a consistent interval, for instance, every 1, 3, or 5 minutes after reconnecting to the kernel, the connection time-outs to the network path should be investigated and increased accordingly.

Set the WebContextURL property

If you're using a reverse proxy server and the URL to your site does not end with the default string /arcgis (all lowercase), you should also set the ArcGIS Notebook Server WebContextURL property. This helps ArcGIS Notebook Server construct the correct URLs on the resources it sends to the end user.

Note:

Use the WebContextURL property to set the ArcGIS Notebook Server URL to match that of its ArcGIS Web Adaptor (such as /notebook).

To change the WebContextURL property, complete the following steps:

Sign in to the ArcGIS Notebook Server Administrator Directory at https://notebookserver.domain.com:11443/arcgis/admin as a user with administrator privileges.
Click system > properties > update.
In the Properties text box, insert the following JSON, substituting your own ArcGIS Notebook Server URL as seen by users outside your organization's firewall:
```
{
   "WebContextURL": "https://notebookserver.domain.com/notebook"
}
```
Click Update.
Restart ArcGIS Notebook Server. On Windows, restart the ArcGIS Server Windows service.

Reverse proxy headers and ArcGIS Notebook Server

When integrating your reverse proxy with ArcGIS Web Adaptor, the following property must be set in the header sent by the reverse proxy server:

X-Forwarded-Host=<FQDN of reverse proxy server>

If this property is set in the header, ArcGIS Web Adaptor will return requests to the reverse proxy server that match the reverse proxy server's URL. For example, a request to the ArcGIS Notebook Server Services Directory (https://reverseproxy.domain.com/arcgis/rest/services) will be returned to the client as the same URL.

If the X-Forwarded-Host header property is not set, ArcGIS Web Adaptor may return the URL of the internal machine where the request was directed, for example, https://notebookserver.domain.com/arcgis/rest/services instead of https://reverseproxy.domain.com/arcgis/rest/services. This is problematic, as clients will not be able to access this URL (commonly noted as a browser 404 error). Also, the client will gain some knowledge about the internal machine.

When troubleshooting communication between clients and ArcGIS Web Adaptor, it is recommended that you set the X-Forwarded-Host header property in the reverse proxy server, as this is a common cause of communication failures. The way you set this header varies depending on your reverse proxy server implementation.

For guidance on how to pass the original host header, see the product documentation for your reverse proxy server.

Configuring your reverse proxy server for a highly available ArcGIS Notebook Server site

When implementing a reverse proxy server that has multiple backend targets running ArcGIS Web Adaptor registered with a single ArcGIS Notebook Server site, there are additional considerations that must be taken into account.

ArcGIS Notebook Server uses websocket connections to communicate with the Python kernel. These websocket connections create a stateful session that must be maintained by the reverse proxy configuration. This is referred to as session stickiness, and it requires a layer 7 (application) load balancer to achieve.

Correct session stickiness can be achieved in Apache with the following:

Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED

<Proxy balancer://web_adaptors_https>
    BalancerMember https://notebook1.domain.com:443 route=notebook1
    BalancerMember https://notebook2.domain.com:443 route=notebook2
    BalancerMember https://notebook3.domain.com:443 route=notebook3

    ProxySet lbmethod=byrequests
    ProxySet stickysession=ROUTEID
</Proxy>

It is also important to proxy the secure websocket (WSS) connections to the same backend targets:

<Proxy balancer://web_adaptors_wss>
    BalancerMember wss://notebook1.domain.com:443 route=notebook1
    BalancerMember wss://notebook2.domain.com:443 route=notebook2
    BalancerMember wss://notebook3.domain.com:443 route=notebook3

    ProxySet lbmethod=byrequests
    ProxySet stickysession=ROUTEID
</Proxy>

Feedback on this topic?