Get your setup working faster. Join our Discord for optimisation tips from elite testers.

Test certificate based authentication

Test authentication using BrowserStack App Automate.

Test certificate-based authentication using multiple certificate formats (.pfx, .cer, .mobileconfig) on BrowserStack devices. You can automate certificate installation and sign in to dependent apps without manually entering passwords, streamlining your authentication testing workflow.

The certificate upload feature (supports .pfx, .cer, .mobileconfig) is currently in beta. To enable this feature for your account, contact BrowserStack support.

You can upload certificate files in the following formats:

.pfx (Personal Information Exchange)
.cer (Certificate)
.mobileconfig (Mobile Configuration Profile)

Maximum file size: 10 MB per certificate file.

OS	OS version
iOS	v15 and above
Android	v7 and above

Upload your file to BrowserStack

Run the following upload media cURL command to upload your file to BrowserStack servers:

Copy

Here is a sample cURL response. It returns the media_url parameter value.

Copy

BrowserStack creates a Custom_Files folder in Files app → On My iPhone → Your app's directory. You can find the file under the App directory on your device.

Set the capability in test script

The password parameter is mandatory for PFX certificates. If you do not set a password, you must still pass an empty string (“”). For other certificate types (.cer, .mobileconfig), the password field is optional.

To use certificate based authentication, set the customCertificates capability with the certificateId as the value of the media_url parameter returned in the API response. Use the customCertificates capability for W3C protocol and browserstack.customCertificates capability for JSON Wire protocol in your test scripts:

W3C Protocol
JSON Wire Protocol

      Java
    

      Node.js
    

      C#
    

      PHP
    

      Python
    

      Ruby
    
import java.util.HashMap;
import java.util.ArrayList;
import java.util.Map;

DesiredCapabilities capabilities = new DesiredCapabilities();
HashMap<String, Object> browserstackOptions = new HashMap<String, Object>();

ArrayList<Map<String, String>> customCerts = new ArrayList<>();
Map<String, String> cert1 = new HashMap<>();
cert1.put("certificateId", "media://90c7a8h8dc82308108734e9a46c24d8f01de12881");
cert1.put("password", "xxxxxxxx");
customCerts.add(cert1);

Map<String, String> cert2 = new HashMap<>();
cert2.put("certificateId", "media://734e9a46c24d8f01de1288190c7a8h8dc82308108");
customCerts.add(cert2);

browserstackOptions.put("customCertificates", customCerts);
capabilities.setCapability("bstack:options", browserstackOptions);
var capabilities = {
	'bstack:options': {
		'customCertificates': [
			{
				"certificateId": "media://90c7a8h8dc82308108734e9a46c24d8f01de12881",
				"password": "xxxxxxxx"
			},
			{
				"certificateId": "media://734e9a46c24d8f01de1288190c7a8h8dc82308108"
			}
		]
	}
}
using System.Collections.Generic;

DesiredCapabilities capability = new DesiredCapabilities();
Dictionary<string, object> browserstackOptions = new Dictionary<string, object>();

List<Dictionary<string, string>> customCerts = new List<Dictionary<string, string>>();
Dictionary<string, string> cert1 = new Dictionary<string, string>();
cert1.Add("certificateId", "media://90c7a8h8dc82308108734e9a46c24d8f01de12881");
cert1.Add("password", "xxxxxxxx");
customCerts.Add(cert1);

Dictionary<string, string> cert2 = new Dictionary<string, string>();
cert2.Add("certificateId", "media://734e9a46c24d8f01de1288190c7a8h8dc82308108");
customCerts.Add(cert2);

browserstackOptions.Add("customCertificates", customCerts);
capability.SetCapability("bstack:options", browserstackOptions);
$capabilities = new DesiredCapabilities();
$browserstackOptions = array(
	"customCertificates" => array(
		array(
			"certificateId" => "media://90c7a8h8dc82308108734e9a46c24d8f01de12881",
			"password" => "xxxxxxxx"
		),
		array(
			"certificateId" => "media://734e9a46c24d8f01de1288190c7a8h8dc82308108"
		)
	)
);
$capabilities->setCapability("bstack:options", $browserstackOptions);
desired_cap = {
	'bstack:options': {
		'customCertificates': [
			{
				"certificateId": "media://90c7a8h8dc82308108734e9a46c24d8f01de12881",
				"password": "xxxxxxxx"
			},
			{
				"certificateId": "media://734e9a46c24d8f01de1288190c7a8h8dc82308108"
			}
		]
	}
}
desired_caps = {
	'bstack:options' => {
		'customCertificates' => [
			{
				"certificateId" => "media://90c7a8h8dc82308108734e9a46c24d8f01de12881",
				"password" => "xxxxxxxx"
			},
			{
				"certificateId" => "media://734e9a46c24d8f01de1288190c7a8h8dc82308108"
			}
		]
	}
}

Use browserstack.yml configuration

You can also configure certificate-based authentication in your browserstack.yml file:

Copy

You can upload and use up to 15 certificates in a session for authentication using the browserstack.customCertificates capability.
The password field is only required for .pfx files. .cer and .mobileconfig files do not require a password.
Each additional certificate installation will increase the session start time.
You can view the list of recently uploaded certificates. For more details, refer to the List uploaded media files section in the API reference documentation.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!