Fix certificate pinning failures with network logs

Fix Appium test failures on App Automate that occur when network logs are enabled and your app uses certificate pinning.

If your app uses certificate pinning, your tests can fail when you enable network logs. Network requests between your app and its pinned hosts fail because of how BrowserStack captures network logs, not because of the device. Exclude the pinned hosts from network log capture to fix these failures.

Common issues

When network logs break certificate-pinned traffic, the failure usually shows up in your app’s UI rather than as a BrowserStack error. The following issues might appear:

• Login doesn’t complete, or an infinite loading spinner appears after login.
• Webviews or in-app pages load as blank white screens.
• Maps, ads, live chat, or other content sections don’t load.
• Deep links fail, show an SSL error page, or open in the browser instead of your app.
• Your app shows an “unable to connect to server” or generic network error.
• Payment or third-party redirects, such as a payment gateway login page, don’t open.
• The device logs show SSL handshake errors.

Why certificate pinning fails with network logs

App developers use certificate pinning to prevent man-in-the-middle attacks and enhance the app’s security. Using certificate pinning, the app developer associates, or pins, a remote host or service with its certificate or public keys at the time of development. When the app makes a network request to a remote host, the app compares the pinned certificate with the remote server’s certificate to verify the host’s identity.

BrowserStack uses a MITM proxy to capture network logs. When network logs are enabled, this proxy causes network requests between your app and its pinned hosts to fail.

Third-party SDKs in your app can also pin certificates, so the failing hosts aren’t always your own APIs. For example, ads, maps, and payment SDKs can connect to pinned hosts.

Confirm that network logs cause the failure

Run the same test twice on the same device: once with networkLogs set to true and once with it set to false. If the test passes with network logs disabled and fails with them enabled, the network log proxy is the cause.

Find the hosts to exclude

The hosts to exclude depend on your app. To find them, try the following:

• Ask your app developers which hosts your app and its third-party SDKs pin certificates for.
• Check the device logs of the failed session for SSL handshake errors. These errors show which requests failed.

Exclude certificate-pinned hosts

Use the exclude hosts capability to bypass the BrowserStack MITM proxy for requests to certificate-pinned hosts. Your tests run successfully and BrowserStack still captures network logs for all other hosts. Requests to excluded hosts don’t appear in your network logs.

DesiredCapabilities capabilities = new DesiredCapabilities();
HashMap<String, Object> browserstackOptions = new HashMap<String, Object>();
browserstackOptions.put("networkLogs", "true");
browserstackOptions.put("networkLogsExcludeHosts", new String[]{"api.example.com", "google.com"});
capabilities.setCapability("bstack:options", browserstackOptions);

var capabilities = {
	'bstack:options' : {
		'networkLogs': 'true',
		'networkLogsExcludeHosts': ['api.example.com', 'google.com'],
	}
}

AppiumOptions capabilities = new AppiumOptions();
Dictionary<string, object> browserstackOptions = new Dictionary<string, object>();
browserstackOptions.Add("networkLogs", "true");
browserstackOptions.Add("networkLogsExcludeHosts", new[] {"api.example.com", "google.com"});
capabilities.AddAdditionalCapability("bstack:options", browserstackOptions);

$caps = array(
	'bstack:options' => array(
		"networkLogs" => "true",
		"networkLogsExcludeHosts" => ["api.example.com", "google.com"],
	),
);

desired_cap = {
	'bstack:options' : {
		'networkLogs': 'true',
		'networkLogsExcludeHosts': ['api.example.com', 'google.com']
	}
}

capabilities = {
    'bstack:options' => {
        'networkLogs' => 'true',
        'networkLogsExcludeHosts' => ['api.example.com', 'google.com']
    }
}

DesiredCapabilities capabilities = new DesiredCapabilities();
HashMap<String, Object> browserstackOptions = new HashMap<String, Object>();
browserstackOptions.put("networkLogs", "true");
browserstackOptions.put("networkLogsExcludeHosts", "^(.+\\.)?example.com");
capabilities.setCapability("bstack:options", browserstackOptions);

var capabilities = {
	'bstack:options' : {
		'networkLogs': 'true',
		'networkLogsExcludeHosts': '^(.+\\.)?example.com',
	}
}

AppiumOptions capabilities = new AppiumOptions();
Dictionary<string, object> browserstackOptions = new Dictionary<string, object>();
browserstackOptions.Add("networkLogs", "true");
browserstackOptions.Add("networkLogsExcludeHosts", @"^(.+\.)?example.com");
capabilities.AddAdditionalCapability("bstack:options", browserstackOptions);

$caps = array(
	'bstack:options' => array(
		"networkLogs" => "true",
		"networkLogsExcludeHosts" => '^(.+\.)?example.com',
	),
);

desired_cap = {
	'bstack:options' : {
		'networkLogs': 'true',
		'networkLogsExcludeHosts': r'^(.+\.)?example.com'
	}
}

capabilities = {
    'bstack:options' => {
        'networkLogs' => 'true',
        'networkLogsExcludeHosts' => '^(.+\.)?example.com'
    }
}

DesiredCapabilities desiredCapabilities = new DesiredCapabilities();
desiredCapabilities.setCapability("browserstack.networkLogs", "true");
desiredCapabilities.setCapability("browserstack.networkLogsExcludeHosts", new String[]{"api.example.com", "google.com"});

var capabilities = {
	'browserstack.networkLogs': 'true',
	'browserstack.networkLogsExcludeHosts': ['api.example.com', 'google.com'],
}

DesiredCapabilities capability = new DesiredCapabilities();
capability.SetCapability("browserstack.networkLogs", "true");
capability.SetCapability("browserstack.networkLogsExcludeHosts", new[] {"api.example.com", "google.com"});

$capabilities = new DesiredCapabilities();
$capabilities->setCapability("browserstack.networkLogs", "true");
$capabilities->setCapability("browserstack.networkLogsExcludeHosts", ["api.example.com", "google.com"]);

desired_cap = {
	'browserstack.networkLogs': 'true',
	'browserstack.networkLogsExcludeHosts': ['api.example.com', 'google.com']
}

desired_caps = {
    'browserstack.networkLogs' => 'true',
    'browserstack.networkLogsExcludeHosts' => ['api.example.com', 'google.com']
}

DesiredCapabilities desiredCapabilities = new DesiredCapabilities();
desiredCapabilities.setCapability("browserstack.networkLogs", "true");
desiredCapabilities.setCapability("browserstack.networkLogsExcludeHosts", "^(.+\\.)?example.com");

var capabilities = {
	'browserstack.networkLogs': 'true',
	'browserstack.networkLogsExcludeHosts': '^(.+\\.)?example.com',
}

DesiredCapabilities capability = new DesiredCapabilities();
capability.SetCapability("browserstack.networkLogs", "true");
capability.SetCapability("browserstack.networkLogsExcludeHosts", @"^(.+\.)?example.com");

$capabilities = new DesiredCapabilities();
$capabilities->setCapability("browserstack.networkLogs", "true");
$capabilities->setCapability("browserstack.networkLogsExcludeHosts", '^(.+\.)?example.com');

desired_cap = {
	'browserstack.networkLogs': 'true',
	'browserstack.networkLogsExcludeHosts': r'^(.+\.)?example.com'
}

desired_caps = {
    'browserstack.networkLogs' => 'true',
    'browserstack.networkLogsExcludeHosts' => '^(.+\.)?example.com'
}

If excluding hosts doesn’t fix the failure

Try these fixes in order:

1. Disable network logs for the session by setting networkLogs to false, its default value.
2. If that doesn’t resolve the failure, disable SSL pinning in your test builds only. Never disable SSL pinning in production builds.

Related topics

• Troubleshoot network logs
• Debug network logs generation issues or insecure certificate error issues
• Network and connection issues