Sauce Connect Proxy Setup with Additional Proxies

This is a guide for users who have an existing internal network proxy through which outbound communication is routed from their network to the public internet. If this sounds like your setup, additional proxy configuration of the Sauce Connect Proxy tunnel is required:

Between the internet and the machine hosting Sauce Connect Proxy.
Between the machine hosting Sauce Connect and the machine hosting the website or mobile app you want to test.

To configure Sauce Connect Proxy to use your proxy or proxies, you will need to include one or more Sauce Connect command-line options (see the Sauce Connect Proxy Command-Line Quick Reference Guide) in your test script.

Warning About Man-in-the-Middle Proxies

If you use a Man-in-the-Middle proxy to monitor network traffic, it must be configured to allow the TLS connection and proprietary protocol used by Sauce Connect Proxy to communicate with the Sauce Labs virtual machines that are running your tests. If it will allow only HTTP or HTTPS sessions, it will drop the inbound Sauce Connect Proxy connection.

See the Sauce Connect Proxy Tunnel Startup Diagram for more information about how Sauce Connect Proxy initiates and maintains the connection with the Sauce Labs browser cloud.

What You'll Need

Review the Basic Setup to confirm that your system and network architecture are compatible with Sauce Connect Proxy.

Setting Up Sauce Connect Proxy With Your Proxy

There are several different ways to set up Sauce Connect Proxy to use a proxy server that is on your network, depending on the desired behavior. There are three types of network traffic that are relevant to using proxy servers with Sauce Connect Proxy:

REST API Traffic: The Sauce Connect client running on your network maintains a lightweight connection to our REST API that simply tells our servers basic information about the status of Sauce Connect's status (for example, starting up, ready, stopping)
SUT Traffic: The Sauce Connect client communicates with the Site Under Test (SUT) running in your network
Tunnel Traffic: The Sauce Connect client makes a connection to the actual tunnel virtual machine (VM) in the Sauce Labs cloud, created for your Sauce Connect instance The configuration options described below will cause the REST API and SUT traffic to be routed through your proxy. While it is technically possible to route the tunnel traffic through your proxy, it is not recommended because this traffic is already TLS-secured. Also, routing tunnel traffic through your proxy will significantly degrade test performance. This option should only be used if your network does not allow outbound communication over port 443.

Proxied Site Under Test (SUT)

In this configuration, the Site Under Test (SUT) is behind a proxy in order to allow even more control over traffic before it reaches the SUT. This setup is used to control access to the SUT by IP allowlisting or by restricting proxy access to users with valid username/password credentials.

Proxy Auto-Configuration (Automatic)

Proxies and proxy auto-configuration (PAC) (see Proxy auto-config) settings may be configured based on the operating system settings on the machine where it is installed.

On Windows, Sauce Connect Proxy will use the proxy settings for Internet Explorer, as well as the system-wide proxy settings that are set in the Control Panel.
On macOS, Sauce Connect Proxy will use the proxy settings in Preferences/Network. Both proxy and PAC settings are supported.
On macOS and Linux, Sauce Connect Proxy looks for these variables, in this order:
- http_proxy
- HTTP_PROXY
- all_proxy
- ALL_PROXY (they can be in the form http://host.name:port or host.name:port)

When a proxy is detected, Sauce Connect Proxy will route the following traffic through the detected proxy:

all network traffic between the Sauce Connect Proxy client running on your network and the Sauce Labs REST API
all network traffic between the Sauce Connect Proxy client and the SUT

note

Network traffic between the Sauce Connect Proxy client running on your network and the Sauce Connect server will not use the detected proxy unless the --proxy-tunnel flag is specified.

You can disable automatic proxy detection with the command-line option --no-autodetect.

To set up and run Sauce Connect Proxy for this situation, see Basic Setup.

Command Line Configuration (Manual)

If automatic proxy configuration fails, you will need to override the settings or enable proxies when starting Sauce Connect Proxy. There are several command line arguments that you can use to configure proxies manually.

Flag	Description
`-p (--proxy <host:port>)`	Proxy host and port that Sauce Connect Proxy should use to connect to the Sauce Labs REST API and SUT traffic. Can be used on its own or combined with `-w -pac`.
`-p (--proxy <host:port>) -w (--proxy-userpwd <user:pwd>)`	Requires username and password sent via basic authentication to access the proxy specified with `-p`. Can be combined with `-pac`. Note: Do not use this `-p -w` combination with more than one proxy. Multiple proxies requiring auth are not supported.
`-p (-–proxy <host:port>) -T (--proxy-tunnel)`	Reroutes all tunnel traffic through the proxy specified with `-p`. This should only be used as a last resort if the machine running Sauce Connect Proxy cannot send outgoing connections from `port 443`. Cannot be combined with `--pac`.
`--pac url`	Proxy auto-configuration (can be a http(s) or local `file://URL`). Absolute paths are required when specifying a local PAC file (for example, `file://Users/JohnSmith/Desktop/MyPac.pac` on Mac/Linux or `file:///Users/JohnSmith/Desktop/MyPac.pac` on Windows). Can be used on its own or combined with `-p -w`.
`--proxy-localhost`	If the upstream proxy is hosted on `localhost`, add this flag to correctly proxy traffic. By default, any traffic to `localhost` is not sent to an upstream proxy.

Command Line Configuration Using `-p (-–proxy <host:port>)` and `-w (--proxy-userpwd <user:pwd>`)

Using the -p and -w commands together when starting a Sauce Connect Proxy tunnel will route traffic between the Sauce Connect Proxy client on your network and the Sauce REST API through the proxy server specified by the <host:port> argument.

Here are some examples for starting a tunnel using -p and -w:

Mac or Linux
Windows

./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY \
  -p $PROXY_HOST:$PROXY_PORT  -w $PROXY_USERNAME:$PROXY_PASSWORD

.\sc.exe -u %SAUCE_USERNAME% -k %SAUCE_ACCESS_KEY% ^
  -p %PROXY_HOST%:%PROXY_PORT%  -w %PROXY_USERNAME%:%PROXY_PASSWORD%

Command Line Configuration Using `-p (-–proxy <host:port>)` and `-T (--proxy-tunnel)`

The -p and -T combination is generally not recommended and should only be used as a last resort if the machine running Sauce Connect Proxy cannot send outgoing connections from port 443. Using this configuration will slow down your tests because all tunnel traffic will be re-routed through the proxy specified with -p. Your tunnel traffic is already encrypted.

Here are some examples for starting a Sauce Connect Proxy tunnel using -p and -T:

Mac or Linux
Windows

./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY \
  -p $PROXY_HOST:$PROXY_PORT  -w $PROXY_USERNAME:$PROXY_PASSWORD -T

.\sc.exe -u %SAUCE_USERNAME% -k %SAUCE_ACCESS_KEY% ^
  -p %PROXY_HOST:PROXY_PORT%  -w %PROXY_USERNAME%:%PROXY_PASSWORD% -T

Command Line Configuration Using PAC Files (`–pac url`)

Your IT organization may have a PAC file that is used to specify how your own internal proxy servers should be configured.

To have Sauce Connect Proxy with your PAC file, use the --pac url command line option when starting Sauce Connect Proxy. The URL argument can be an http(s) or local file://URL. Absolute paths are required when specifying a local PAC file (for example, file://Users/JohnSmith/Desktop/MyPac.pac on Mac/Linux or file:///C:/Users/JohnSmith/Desktop/MyPac.pac on Windows).

If your PAC file contains multiple proxies, in addition to -pac, you'll need to specify the -p option to designate which proxy will receive the username and password.

Here are some examples for starting a Sauce Connect Proxy tunnel using --pac url:

Mac or Linux
Windows

./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY --pac PAC_FILE_URL

.\sc.exe -u %SAUCE_USERNAME% -k %SAUCE_ACCESS_KEY% --pac PAC_FILE_URL

If you are starting a tunnel for Real Device tests, see Real Device Cloud Setup.

Network Traffic Flow Diagrams

The following diagrams illustrate different Sauce Connect Proxy network flow configurations.

Site Under Test (SUT) Behind a Proxy

Diagram Legend

Term	Definition
SC Host (Sauce Connect Host)	Machine in your network on which the Sauce Connect Proxy app is running.
SUT (Site Under Test)	The site that you're testing.
Sauce SC Host (Tunnel VM)	Virtual machine that hosts Sauce Connect Proxy on the Sauce Labs side.

Network Traffic Flow With Tunnel Established using `-p`

Sauce Connect Proxy client sends new tunnel request to proxy.
Proxy forwards request to REST API.
REST API initiates a request to the system to create a new Tunnel VM.
REST API returns DNS name of Tunnel VM via your proxy.
Your proxy forwards DNS name to Sauce Connect Proxy client.
Sauce Connect Proxy client makes a connection request to Tunnel VM using DNS name.

At this point, the tunnel is established between the Sauce Connect Client and the Tunnel VM.

Network Traffic Flow When a Test is Run Through a Tunnel Started with `-p`

Network traffic flow through a tunnel started with '-p'

Selenium/Appium test code sends an HTTPS request to the VM or Real Device that was created for this test (for example, 'GET www.saucedemo.com').
Test VM or Device sends this request to Tunnel VM in order to access Site Under Test (SUT).
Tunnel VM forwards this request to Sauce Connect Proxy client via the secure tunnel.
Sauce Connect Proxy client forwards the request to SUT via your proxy.
Site Under Test returns response to Sauce Connect Proxy client via your proxy.
Sauce Connect Proxy client sends response to Tunnel VM via secure tunnel.
Tunnel VM sends response to Test VM.
Test VM sends results back to Selenium/Appium Test cloud.

Throughout the lifetime of a tunnel, Sauce Connect Proxy client sends status information to Sauce Labs REST API via your proxy.

Network Traffic Flow when a Tunnel is Established Using `-T`

Network traffic flow through a tunnel established using '-T'

Sauce Connect Proxy client sends new tunnel request to REST API via your proxy.
REST API initiates a request to the system to create a new Tunnel VM.
REST API sends DNS name of Tunnel VM to Sauce Connect Proxy client via your proxy.
Sauce Connect Proxy client sends connect request to Tunnel VM via your proxy.

At this point, the tunnel is established between the Sauce Connect Proxy client and the Tunnel VM, but all traffic will go through your proxy.

Network Traffic Flow When a Test is Run Through a Tunnel Started Using `-T`

Network traffic flow through a tunnel started using '-T'

Selenium/Appium test code sends an HTTPS request to the VM or Real Device that was created for this test (for example, GET www.saucedemo.com).
Test VM or device sends this request to Tunnel VM in order to access Site Under Test (SUT).
Tunnel VM forwards this request to Sauce Connect Proxy client through tunnel via your proxy.
Sauce Connect Proxy client forwards the request to SUT via your proxy.
Site Under Test returns response to Sauce Connect Proxy client via your proxy.
Sauce Connect Proxy client sends response to Tunnel VM through tunnel via your proxy.
Tunnel VM sends response to Test VM.
Test VM sends results back to Selenium/Appium Test cloud.

Throughout the lifetime of a tunnel, Sauce Connect Proxy client sends status information to Sauce Labs REST API via your proxy.

Setting Up with Third Party Proxies

Charles Proxy Configuration

The Charles Proxy is useful for monitoring traffic passing between your Sauce VM or RDC device and your site under test. To begin, you'll need to create a PAC file that matches the REST and tunnel VM hostnames, then use the Charles Proxy for everything else.

Download and install Charles Proxy (see the Charles Web Debugging Proxy App.
Open Charles Proxy.
To enable your machine to trust SSL/TLS certificates, in Charles Proxy, click Help, and then click SSL Proxying > Install Charles Root Certificate. For more information, see SSL Certificates.

Create a pac.js file for Sauce Connect Proxy:

function FindProxyForURL(url, host) {
    if (shExpMatch(host, "*.miso.saucelabs.com*") ||
        shExpMatch(host, "*.saucelabs.com") ||
        shExpMatch(host, "saucelabs.com")) {
        // KGP and REST connections. Another proxy can also be specified.
        return "DIRECT";
    }

    // Test HTTP traffic, route it through the Charles proxy.
    return "PROXY localhost:8890";
}

Start Charles Proxy.
To change to an open port, in Charles Proxy, click Proxy and then click Proxy Settings. Under HTTP Proxy, enter an open port (for example, port 8890) and then click OK.

Start your Sauce Connect Proxy tunnel:

Mac or Linux
Windows

./sc --pac file://Users/JohnSmith/workspace/scstuff/pac.js

./sc --pac file:///C:/Users/JohnSmith/workspace/scstuff/pac.js

Start your test using the proxy, then observe the traffic in Charles Proxy.
Copy the file to the same directory as Sauce Connect Proxy, and then start Sauce Connect Proxy.

WonderProxy

You can use WonderProxy for GeoIP website testing with Sauce Connect Proxy. For more information, see Testing with Sauce Labs and WonderProxy.

Using Multiple Proxies

If you have multiple proxies (two or more), you may need to edit the PAC file to reflect that. In a multi-proxy environment, you may have:

A proxy specifically for the staging area or SUT
A transparent proxy that connects you to the internet (see Transparent proxy for more information)

To confirm if you have additional proxies, you can use basic curl commands. If curl -v google.com doesn't return anything, but curl -v --proxy external.proxy.com:8080 google.com does return something, you have at least one proxy required to access the public internet.

If curl -v --proxy external.proxy.com private.mysite.com does not get a response from your SUT, you may need to use a different proxy, such as internal.proxy.com:8080, access your SUT. In this case, you'd need your PAC file to reflect your network setup:

multiproxy proxy.pac
function FindProxyForURL(url, host) {
// Sauce domain calls required to start a tunnel
if (
shExpMatch(host, '*.miso.saucelabs.com*') ||
shExpMatch(host, '*.saucelabs.com') ||
shExpMatch(host, 'saucelabs.com')
) {
// Send the required Sauce Traffic
// to the External proxy
return 'PROXY external.proxy.com:8080'
}

// Test VM HTTP traffic gets routed to the
// Internal proxy to reach the site Under Test
return 'PROXY internal.proxy.com:8080'
}

Here's an example of a single-proxy PAC setup for public internet access:

single_proxy.pac
// A proxy is required to reach external resources
function FindProxyForURL(url, host) {
// Internal calls for resources in your network
if (
shExpMatch(host, '*.auth.my-company.com') ||
shExpMatch(host, '*staging.my-company.com') ||
shExpMatch(host, 'internal-resource1.com')
) {
return 'DIRECT'
}

// All other traffic should
// go to the public internet via proxy
return 'PROXY my-company.org:8880'
}

Warning About Man-in-the-Middle Proxies​

What You'll Need​

Setting Up Sauce Connect Proxy With Your Proxy​

Proxied Site Under Test (SUT)​

Proxy Auto-Configuration (Automatic)​

Command Line Configuration (Manual)​

Command Line Configuration Using -p (-–proxy <host:port>) and -w (--proxy-userpwd <user:pwd>)​

Command Line Configuration Using -p (-–proxy <host:port>) and -T (--proxy-tunnel)​

Command Line Configuration Using PAC Files (–pac url)​

Network Traffic Flow Diagrams​

Site Under Test (SUT) Behind a Proxy​

Network Traffic Flow With Tunnel Established using -p​

Network Traffic Flow When a Test is Run Through a Tunnel Started with -p​

Network Traffic Flow when a Tunnel is Established Using -T​

Network Traffic Flow When a Test is Run Through a Tunnel Started Using -T​

Setting Up with Third Party Proxies​

Charles Proxy Configuration​

WonderProxy​

Using Multiple Proxies​