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

   # sudo 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

   # sudo update-ca-trust extract
   

   Restart the PrivX Web Proxy service to apply the changes:

   Bash

   # sudo systemctl restart privx-web-proxy
   

Accepting SHA-1 Signatures in X.509 Certificates

By default web-proxy does NOT accept certificates that have been signed using the SHA-1 hash algorithm. These kind of certificates have not been issued by major certificate authorities since 2016, because SHA-1 can no longer be considered a secure hash algorithm.

To make web-proxy accept certificates with SHA-1 signatures, you can declare the GODEBUG=x509sha1=1 environment variable in /opt/privx/scripts/web-proxy.sh:

#!/bin/sh

dir="/opt/privx/bin"
name=`basename $0 .sh`
stdout_log="/var/log/privx/$name.log"
stderr_log="/var/log/privx/$name.log"
loglevel=`echo ${SSH_LOG_LEVEL:-${DEFAULT_LOG_LEVEL:-INFO}}`
tracelevel=`echo ${SSH_TRACE:-${DEFAULT_TRACE:-0}}`

export GODEBUG="x509sha1=1"
...

❗️

Allowing SHA-1 Signatures

Accepting certificates with SHA-1 signatures will reduce the security of the web-proxy component. This mode should be used with caution and only when strictly needed.

Allowing Certificate Validation Exceptions

Certificate validation exceptions can be allowed for specific targets or certificate issuer subject names via the following configuration variables in /opt/privx/etc/web-proxy-config.toml:

# TLS insecure verify domains. Server TLS certificate validation errors are ignored for certificates when destination
# hostname as sent in TLS SNI matches one of the patterns specified here. The patterns are given as glob patterns.
# This parameter should be used with caution and only when strictly needed.
# Example:
# tls_insecure_verify_domains = [
# "legacy-router.io", "*.legacy-domain.io"
# ]
tls_insecure_verify_domains = []

# TLS insecure verify certificate subject patterns. Server TLS certificate validation errors are ignored for certificates
# whose subject name matches one of the patterns specified here. The patterns are given as PKIX names with glob patterns
# in attribute values. This parameter should be used with caution and only when strictly needed.
# Example:
# tls_insecure_verify_cert_subjects = [
# "CN=*/O=IT/OU=Legacy Routers"
# ]
tls_insecure_verify_cert_subjects = []

📘

Note

Allowing certificate validation exceptions will reduce the security of the web-proxy component. These configuration variables should be used with caution and only when strictly needed to workaround certificate validation issues with legacy targets.

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 service:

   Bash

   # systemctl restart privx-web-proxy
   

   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
   

Enable Asian Font Support for Web Connections

By default, PrivX Carriers use browser versions that do not support Asian fonts. If you need to enable asian-font support, perform the following on all your Carrier machines:

1. Pull the appropriate browser image(s) from ECR Public Gallery to the Carrier machine:

   • sshprivx/privx_browser_chromium - PrivX Chromium container including Asian language support
   • sshprivx/privx_browser_firefox - PrivX Chromium container including Asian language support

   For example, to pull the Chromium container with Asian font support:

   docker pull public.ecr.aws/sshprivx/privx_browser_chromium
   

   If the Carrier machine cannot access the Internet, you will need to perform a Manual Browser Import.

2. Specify the browser in the Carrier configuration at /opt/privx/etc/carrier-config.toml, under the [web_browsers] section. For example:

   [web_browsers]
   # Name of default docker image used to launch web containers.
   # Default image will be used to serve web connection requests, when chromium and firefox browser images are not set.
   default = "public.ecr.aws/sshprivx/privx_browser_firefox"
   
   # Name of chromium docker image used to launch web containers.
   chromium = "public.ecr.aws/sshprivx/privx_browser_chromium"
   
   # Name of firefox docker image used to launch web containers.
   firefox = "public.ecr.aws/sshprivx/privx_browser_firefox"
   

   The possible values for default, chromium, and firefox are:

   • public.ecr.aws/sshprivx/privx_browser_firefox_lite - Firefox lite version.
   • public.ecr.aws/sshprivx/privx_browser_firefox - Firefox with Asian-font support.
   • public.ecr.aws/sshprivx/privx_browser_chromium_lite - Chromium lite version.
   • public.ecr.aws/sshprivx/privx_browser_chromium - Chromium with Asian-font support.

3. Restart the Carrier service to apply your changes:

   Shell

   sudo systemctl restart privx-carrier
   

Manual Browser Import

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

📘

Note

The following examples are for pulling the Chromium image with Asian language support. The example commands must be adapted depending for your desired browser and your PrivX version.

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

docker pull public.ecr.aws/sshprivx/privx_browser_chromium:<version>

2. Then, export the image:

docker save public.ecr.aws/sshprivx/privx_browser_chromium > privx_browser_chromium.tar

3. Copy the tar file to your Carriers.

4. On all Carriers, import the image (and tag if necessary):

docker load < privx_browser_chromium.tar

Change Browser for Web Connections

You can change the web-connection browser globally and per web service.

To change the browser globally:

1. Specify the browser in the Carrier configuration at /opt/privx/etc/carrier-config.toml, in the default setting under [web_browsers].

   For example, to use Firefox by default:

   default = "public.ecr.aws/sshprivx/privx_browser_firefox_lite"
   

   Alternatively, to use Chromium by default:

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

   📘

   Note

   The lite browser versions included by default do not support Asian fonts. For more information about enabling Asian-font support, see Enable Asian Font Support for Web Connections.

2. Restart the Carrier service to apply your changes:

   Bash

   # systemctl restart privx-carrier
   

To change the browser per web service:

1. Edit the target host via Administration→Hosts.

2. Under Services, expand the Additional Settings of the Web service, then set the Browser

   

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

Proxy Chaining

Web-proxy can forward outgoing requests via SOCKS5 and http CONNECT proxies.

The proxy URL and proxy bypass list can be configured in /opt/privx/etc/web-proxy-config.toml file, or via the ALL_PROXY and NO_PROXY environment variables:

# Proxy URL specifies the http connect or socks proxy to use when connecting to target servers.
# Extender connections are never connected through the proxy.
# Supported proxy URL schemes:
#  "http": http connect protocol
#  "https": http connect protocol over a TLS connection
#  "socks5" / "socks5h": socks5 protocol
# If the value is empty then the proxy URL and no proxy list are read from the ALL_PROXY and NO_PROXY environment
# variables.
# Example:
# proxy_url = "http://proxyuser:[email protected]:8080"
proxy_url = ""

# No proxy defines target servers which should be connected directly bypassing the proxy. The target servers are specified
# as a comma separated list of ip addesses, cidrs, domain patterns or hostnames.
# Example:
# no_proxy = "10.0.0.1,192.168.0.0/24,*.internal.privx.io,directly-connectable.privx.io"
no_proxy = ""

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