Accessing web services via PrivX

The basic use case for accessing web servers and routing traffic (HTTP/HTTPS/WS/WSS) via PrivX requires three components:

• PrivX core server
• PrivX Carrier
• PrivX Web Proxy

Carrier and Web Proxy must always be installed in pairs, with each requiring its own config file.
Although they can be located on the same server, separate server instances are recommended in production environments for security reasons.

After configuring the web service for the PrivX host config, web requests from the PrivX UI are routed via Carrier browser to PrivX Web Proxy, which then connects to the actual web target.
Carrier and Web Proxy can be installed on a different network, as long as both are able to open a connection to the PrivX API endpoint.

For latency and usability reasons, the Carrier should be located as close to the PrivX server instance as possible.

To properly extend web connectivity to different networks, an Extender can be used to route the Web Proxy traffic.

By using the Web Access Gateway name as the address prefix (in this example, 'web1') in the host service config, web traffic can be routed directly via Carrier and Web Proxy to the target address.
Alternatively, the Web Access Gateway's Routing Prefix can be used to achieve HA.

📘

NOTE

Carrier and Web Proxy need to be always installed in pairs, even when configuring an HA setup. Each component requires their own configuration file (downloadable via PrivX UI).
Both can be installed to the same server instance, but for security reasons, we recommend using two separate servers in production environments.

Routing web traffic to VPN/VPC via PrivX Extender

For routing web traffic to different networks, an Extender can be used. (see extender config instructions)
This allows using a single Carrier+Web Proxy setup to reach multiple VPN networks, reducing infrastructure costs and simplifying maintenance.

The image above illustrates the connectivity between PrivX components. PrivX Carrier, Web Proxy, and Extender establish a secure web socket connection with the PrivX API endpoint. Outgoing traffic is then tunneled through open WSS connections.

When a web connection is initiated via PrivX Carrier, a sandboxed browser container specific to the session is launched, which then proxies web traffic through PrivX Web Proxy.
By default, when using "web1" prefix for the target host address, the PrivX Web Proxy will route the web traffic to the target web host directly.
For example: web1/https://your.target.server.address-in.network2/something

After configuring the Web Access Gateway to allow routing the traffic via Extender, the address prefix can be changed to network1.
For example: network1/https://your.target.server.address.in.network1/something

In the latter case, the requests do not directly go to the Extender host via PrivX Web Proxy. Instead, web requests are routed by PrivX Web Proxy through an open WSS tunnel to the PrivX server and then through another WSS tunnel to PrivX Extender. The requests are then routed from the Extender host to the target address. DNS resolution for the target address occurs on the Extender host.

To ensure optimal performance with minimal latency, it is recommended to have the PrivX Carrier host located in the same network as the PrivX host(s).
Although the location of the PrivX Web Proxy can affect web request latency, the Carrier host's location has the most significant impact on perceived performance because the browser UI runs in the container on the Carrier host.

To configure Web Proxy to route the traffic via Extender, do the following:

1. Configure PrivX Extender in Administration/Deployment/Deploy PrivX VPC/VPN Extenders. In this example, we name the Extender 'network1'
   
2. Download the Extender config file and Extender RPM package and install it to the host in your target network.
3. To configure the PrivX Web Access Gateway, go to Administration/Deployment/Deploy PrivX Web Access Gateways. In this example, we'll name the configuration 'web1'.
   Set the 'Proxy Address' to include the IP address of the Web Proxy host as viewed from the Carrier host.
   Next, configure the 'Web Proxy Extender Routes' to include the name of the extender, such as 'network1'. This setting enables the PrivX Web Proxy to route web traffic through the specified extender(s), instead of connecting directly to the target host.
   
4. Install and configure PrivX Carrier and PrivX Web Proxy. Download config files via PrivX UI.
5. To configure the web host, navigate to Administration/Hosts. When configuring the Service address, select the extender name 'network1' from the provided list.
   This selection ensures that the Web Proxy routes web traffic through this particular extender.
   Alternatively, if you use the Extender's Routing Prefix instead of the Extender name, you can achieve High Availability (HA) for the selected extenders.
   

📘

NOTE

Extenders are not tied to Web Access Gateway configuration in any way (except referenced by name), you can use the same Extender with different Carriers/Web Proxies.
The requirement for any PrivX components is the ability to connect to PrivX API endpoint and reach all servers behind the load balancer. Note that multi-node HA installations require using HTTPS load balancer with sticky affinity cookie support for PrivX components to work properly.
See https://privx.docs.ssh.com/docs/privx-high-availability-deployment for more information.

Access Restrictions for Web Connections

You can control access to specific websites for all users or users connecting using specific PrivX roles. With this you can prevent users from accessing arbitrary websites by entering URLs, and via links on web targets.
To configure restrictions for all users connecting via specific web proxy, you can modify the Web Proxy configuration file at /opt/privx/etc/web-proxy-config.toml on Web Proxy host.

Note that the query path and parameters are ignored on configured urls. Only schema, domain name and port number are used in the configuration. Wildcards are allowed.

The example below allows all users to access [https://*.gmail.com and https://*.gstatic.com addresses and
user's accessing the host via "developers" role to access https://*.yoursite.com:8080 url.

Add rules like the following to the Web Proxy configuration at /opt/privx/etc/privx-web-proxy.toml​​:

1. Bash

   # Whitelisted urls. Traffic to these domains is always allowed. Wildcards are allowed, for example ['https://*.gmail.com','https://*.gstatic.com']
   # Default is to allow all traffic: ["*"]
   whitelisted_global_urls = [
   "https://*.gmail.com",
   "https://*.gstatic.com"
   ]
   
   # Role whitelisted urls. Traffic to these domains is always allowed for the defined roles. Wildcards are allowed. 
   # Example:
   # whitelisted_role_urls = [
   # "privx-admin=https://*.gmail.com",
   # "privx-admin,developers=https://*.gstatic.com"
   # ]
   # Default: []
   whitelisted_role_urls = [
   "developers=https://*.yoursite.com:8080"
   ]
   
   # Blacklisted urls. Traffic to these domains is blocked, unless explicitly allowed by whitelist. Wildcards are allowed.
   # Default is to block everything: ["*"]
   blacklisted_urls = [
   "*"
   ]
   

2. Restart the ​PrivX Web Proxy service to apply the changes:

   Bash

   # systemctl restart privx-web-proxy
   

You can also configure host specific domain restrictions (since PrivX 16). See Customizing the PrivX Carrier browser for more information.

Trusting Sites with Self-Signed Certificates

Configure trust for any web targets that use self-signed certificates, for the following benefits:

• PrivX users connecting to web targets no longer receive security warnings about insecure server certificates.

• Support websocket connections from the web target.

📘

Note

We recommend setting up web targets before configuring trust for them. For more information about setting up targets in PrivX, see Setting up Hosts.

To trust a web target:

1. On your PrivX Web Proxy, add the CA-certificate chain of the web target to the system trust anchors: Save the CA-certificate-chain file under ​​/etc/pki/ca-trust/source/anchors/​​.

   Then run:

   Bash

   # update-ca-trust extract
   

   Restart the PrivX Web Proxy service to apply the changes:

   Bash

   # systemctl restart privx-web-proxy
   

Changing Web Proxy Port Numbers

To change the Web Proxy ports, you need to edit the following:

📘

Note

In the following examples, replace the port numbers ​18080​, 18443, and ​18444​ with the ports you want to use.

1. On the Carrier host, change the ports in the ​/opt/privx/etc/carrier-config.toml​​ file:

   Bash

   [web_container]
   
   # Web proxy ports for HTTP and HTTPS. The port numbers and Carrier host IP
   # address should match the Web Proxy configuration file in /opt/privx/etc/privx-web-proxy.toml
   # Proxy server IP address is configured via PrivX UI.
   http_proxy_port = 18080
   
   https_proxy_port = 18443
   
   websocket_proxy_port = 18444
   

   After editing the file, restart the Carrier service:

   Bash

   # systemctl restart privx-carrier
   

   On the Web Proxy host, edit the configuration file in ​/opt/privx/etc/web-proxy-config.toml​​ to match the port numbers you entered previously:

   Bash

   # Web proxy listen ports for HTTP and HTTPS.
   # Default http listener port 18080
   http_proxy_port = 18080
   
   # Default https listener port 18443
   https_proxy_port = 18443
   
   # Web Proxy listen port for websocket traffic.
   # Default websocket listener port 18444 
   websocket_proxy_port = 18444
   

   After editing the file, restart the Web Proxy and Squid services:

   Bash

   # systemctl restart privx-web-proxy squid
   

   The Web Proxy host's firewall should allow access to the ports you have specified. Run:

   Bash

   # firewall-cmd --permanent --add-port=18080/tcp
   # firewall-cmd --permanent --add-port=18443/tcp
   # firewall-cmd --permanent --add-port=18444/tcp
   # firewall-cmd --reload
   

Change Browser for Web Connections

To change the browser for web connections:

1. Pull the appropriate browser image(s) from ECR Public Gallery to the Carrier machine. You may find the browser images by searching for sshprivx/privx_browser.

2. Specify the active browser in the Carrier configuration at /opt/privx/etc/carrier-config.toml, with the container_image setting.

   The possible alternatives are:

   • privx_browser_firefox_lite - Firefox lite version.
   • privx_browser_firefox - Firefox with Asian-font support.
   • privx_browser_chromium_lite - Chromium lite version.
   • privx_browser_chromium - Chromium with Asian-font support.

   For example, to use Chromium Lite, first pull the image from ECR repo and tag it:

docker pull public.ecr.aws/sshprivx/privx_browser_chromium_lite:29.0
docker tag public.ecr.aws/sshprivx/privx_browser_chromium_lite:29.0 privx_browser_chromium_lite

and then add the setting to carrier-config.toml:

container_image = "privx_browser_chromium_lite"

alternatively, you can use the full name of container without tagging it first

container_image = "public.ecr.aws/sshprivx/privx_browser_chromium_lite:29.0"

You can also leave out the version number (:29.0), in which case PrivX Carrier will automatically use the matching Carrier version to pull in the matching image:

container_image = "public.ecr.aws/sshprivx/privx_browser_chromium_lite"

3. Restart the Carrier to apply the changes:

   Bash

   sudo systemctl restart privx-carrier
   

   Subsequent web connections via this Carrier are provided using the new browser.

If your Carrier instance does not allow public Internet connections to ECR, you can move the container image manually.

1. First, pull the image from ECR using a machine with Internet connectivity:

docker pull public.ecr.aws/sshprivx/privx_browser_chromium_lite:29.0

2. Then, export the image:

docker save public.ecr.aws/sshprivx/privx_browser_chromium_lite:29.0 > chromium_lite_29.tar

3. Copy the tar file to the target host.

4. Import the image (and tag if necessary):

docker load < chromium_lite_29.tar

5. Make sure that the container_image setting in carrier-config.toml refers to this imported image name.

📘

Note

Chromium does not support password manager.

Web Proxy TLS version and cipher suites

The default TLS versions for incoming and outgoing traffic and used cipher suites can be configured in web proxy config file:

[tls.server]
# Minimum TLS version for incoming connections from Carrier. 1.2 or above. Default is 1.3
# minVersion = "1.2"
minVersion = "1.3"

# TLS 1.2 cipher suites. TLS 1.3 cipher suites are not configurable.
# If left empty, list of default cipher suites is used, with a preference order based on hardware performance
# TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 for TLS 1.2 is required by HTTP/2 spec: https://tools.ietf.org/html/rfc7540#section-9.2.2
# Example:
cipherSuites = [
  "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
  "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
  "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
  "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
  "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
  "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
]

[tls.client]
# Minimum TLS version for outgoing connections to target host. 1.0 or above. Default is 1.2
# Version numbers below 1.2 not recommended for security reasons.
# minVersion = "1.0"
minVersion = "1.2"

# TLS 1.2 cipher suites. TLS 1.3 cipher suites are not configurable.
# If left empty, list of default cipher suites is used, with a preference order based on hardware performance
# TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 for TLS 1.2 is required by HTTP/2 spec: https://tools.ietf.org/html/rfc7540#section-9.2.2
# Example:
cipherSuites = [
  "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
  "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
  "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
  "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
  "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
  "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
]

Custom Load-Balancer Support

If you are using PrivX Components (Extender, Carrier or Web-Proxy) in HA configuration, your load balancer must support sticky-session cookies (affinity cookies).

To properly resolve HA services behind the load balancer, the affinity cookie set by load balancer needs to be added to PrivX components' configuration files.

By default, configuration includes support for AWS, Azure, Google Cloud and Kubernetes Ingress default cookie names. For Nginx load-balancer support, see Example Nginx load balancer configuration.

If your PrivX HA deployment uses a custom load balancer, ensure that its session-affinity cookie (also known as a sticky-session cookie) is accepted by all your PrivX Carriers and PrivX Web-Proxies:

1. Add the name of the session-affinity cookie to the ​known_lb_cookies​​ setting. The setting is located in the following configuration files, for Carriers and Web-Proxies respectively:

   • ​​/opt/privx/etc/carrier-config.toml​​

   • ​​/opt/privx/etc/web-proxy-config.toml​​

2. Restart the Carrier and Web-Proxy services. On your Carriers, run:

   Bash

   # systemctl restart privx-carrier
   

   And on your Web-Proxies, run:

   Bash

   # systemctl restart privx-web-proxy
   

   📘

   Note

   If your PrivX HA deployment also includes Extenders, configure those to accept your session-affinity cookie as well, according to the instructions at High-Availability Deployment.

For more information, see Websockets and the PrivX Carrier browser and Customizing the PrivX Carrier browser

Display Carrier and Web Proxy Host IP on Status Page

When a Carrier or Web Proxy is registered to PrivX via a load balancer, the IP of the load balancer is displayed in the PrivX status page for this component. To display the host IP instead, perform the following on all PrivX servers:

1. Edit /opt/privx/etc/shared-config.toml and set strip_how_many_x_forwarded_for_client_ips = 1.

2. Restart PrivX
   systemctl restart privx

Allowing Popups

By default the web browser for HTTP/HTTPS targets disallows all popups.

To enable popups, perform the following on your Carrier machines:

1. Enable the enable_popups option in the Carrier configuration file ​​/opt/privx/etc/carrier-config.toml​​.

2. Restart the carrier service to apply your settings:

   Bash

   systemctl restart privx-carrier