Using a proxy in Puppeteer

Both browserless, and Chrome itself, support the usage of external proxies. In order to fully utilize a 3rd-party proxy you'll need to do two things:

• Specify the address of where the proxy is with the --proxy-server switch.
• Optionally, you'll also need to send in your username and password if the proxy is authenticated.

Specifying the proxy

Regardless of whether or not you're using our REST API's or the puppeteer integration, you'll need to specify where the proxy is. Chrome has a command-line flag to do this, and we support this in browserless via the following query-string parameter:

?--proxy-server=https://YOUR-PROXY-SERVER-DOMAIN:PORT

If you're using a proxy that doesn't require a password (maybe just an IP address filter), then that's it! You're free to now use this proxy going forward! Otherwise read on.

Using username and password

Method 1: page.authenticate

Most proxies will require some means of authentication. There's generally two ways you can do this in Puppeteer, and also in browserless. The first more common method is the page.authenticate:

await page.authenticate({
    username: 'joel',
    password: 'browserless-rocks',
});

Doing this will apply these parameters to your network requests going forward.

In our REST API's you can specify these fields with the following in your POST JSON body. These parameters work for the pdf, content and screenshot APIs:

{
    "authenticate": {
        "username": "joel",
        "password": "browserless-rocks"
    }
}

Method 2: page.setExtraHTTPHeaders

The other mechanism is to use HTTP headers to send in extra authorization information. Puppeteer makes this pretty easy by allowing us to send in new HTTP headers via page.setExtraHTTPHeaders:

// Remember to base64 encode your username:password!
await page.setExtraHTTPHeaders({
    'Proxy-Authorization': 'Basic username:password',
    // OR
    Authorization: 'Basic username:password',
});

Refer to your libraries documentation on what the name of the headers is, and how to properly encode it.

We also allow this in our REST APIs as well, via the setExtraHTTPHeaders property:

{
    "setExtraHTTPHeaders": {
        "Proxy-Authorization": "Basic username:password",
        // OR
        "Authorization": "Basic username:password"
    }
}

This will allow your REST APIs to utilize the prior provided proxy!