Client Certificates

Configure certificate authority (CA) and client certificates to use within tests on a per-URL basis.

Syntax

clientCertificates (Object[])

An array of objects defining the certificates. Each object must have the following properties

PropertyTypeDescription
urlStringURL to match requests against. Wildcards following minimatch rules are supported.
caArray(Optional) Paths to one or more CA files to validate certs against, relative to project root.
certsObject[]A PEM format certificate/private key pair or PFX certificate container

Each object in the certs array can define either a PEM format certificate/private key pair or a PFX certificate container.

A PEM format certificate/private key pair can have the following properties:

PropertyTypeDescription
certStringPath to the certificate file, relative to project root.
keyStringPath to the private key file, relative to project root.
passphraseString(Optional) Path to a text file containing the passphrase, relative to project root.

A PFX certificate container can have the following properties:

PropertyTypeDescription
pfxStringPath to the certificate container, relative to project root.
passphraseString(Optional) Path to a text file containing the passphrase, relative to project root.

Usage

To configure CA / client certificates within your Cypress configuration, you can add the clientCertificates key to define an array of client certificates as shown below:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  clientCertificates: [
    {
      url: 'https://a.host.com',
      ca: ['certs/ca.pem'],
      certs: [
        {
          cert: 'certs/cert.pem',
          key: 'certs/private.key',
          passphrase: 'certs/pem-passphrase.txt',
        },
      ],
    },
    {
      url: 'https://b.host.com/a_base_route/**',
      ca: [],
      certs: [
        {
          pfx: '/home/tester/certs/cert.pfx',
          passphrase: '/home/tester/certs/pfx-passphrase.txt',
        },
      ],
    },
    {
      url: 'https://a.host.*.com/',
      ca: [],
      certs: [
        {
          pfx: 'certs/cert.pfx',
          passphrase: 'certs/pfx-passphrase.txt',
        },
      ],
    },
  ]
})
import { defineConfig } from 'cypress'

export default defineConfig({
  clientCertificates: [
    {
      url: 'https://a.host.com',
      ca: ['certs/ca.pem'],
      certs: [
        {
          cert: 'certs/cert.pem',
          key: 'certs/private.key',
          passphrase: 'certs/pem-passphrase.txt',
        },
      ],
    },
    {
      url: 'https://b.host.com/a_base_route/**',
      ca: [],
      certs: [
        {
          pfx: '/home/tester/certs/cert.pfx',
          passphrase: '/home/tester/certs/pfx-passphrase.txt',
        },
      ],
    },
    {
      url: 'https://a.host.*.com/',
      ca: [],
      certs: [
        {
          pfx: 'certs/cert.pfx',
          passphrase: 'certs/pfx-passphrase.txt',
        },
      ],
    },
  ]
})
{
  "clientCertificates": [
    {
      "url": "https://a.host.com",
      "ca": [
        "certs/ca.pem"
      ],
      "certs": [
        {
          "cert": "certs/cert.pem",
          "key": "certs/private.key",
          "passphrase": "certs/pem-passphrase.txt"
        }
      ]
    },
    {
      "url": "https://b.host.com/a_base_route/**",
      "ca": [],
      "certs": [
        {
          "pfx": "/home/tester/certs/cert.pfx",
          "passphrase": "/home/tester/certs/pfx-passphrase.txt"
        }
      ]
    },
    {
      "url": "https://a.host.*.com/",
      "ca": [],
      "certs": [
        {
          "pfx": "certs/cert.pfx",
          "passphrase": "certs/pfx-passphrase.txt"
        }
      ]
    }
  ]
}

History

VersionChanges
8.0.0Added Client Certificates configuration options