Playwright Client Certificate Authentication

0.0.3 · active · verified Tue Apr 21

playwright-client-certificate-login is a Node.js utility, currently at version 0.0.3, designed to streamline client certificate-based authentication within Playwright automation scripts. It abstracts the complexities of configuring Playwright's browser context to utilize PFX/PKCS12 files or separate PEM certificate and key files, including their associated passphrases. The library provides a `CertificateAuthSession` class that manages the entire authentication process, from launching a browser and navigating to the specified URL, to making the authenticated browser context, page, cookies, and headers accessible. Given its early version, the package is in active development with an implied irregular release cadence, primarily focusing on robust client certificate handling for scenarios such as SAP BTP and other enterprise authentication systems.

Common errors

```
Error: Required options are missing
```
cause One or more mandatory options (e.g., `origin`, `url`, and a certificate/key pair) were not provided to the `CertificateAuthSession` constructor.

fix Ensure `origin`, `url`, and one of (`pfxPath`/`pfxBuffer`) or (`certPath`/`certBuffer` and `keyPath`/`keyBuffer`) are supplied in the options object.
```
Error: Certificate files cannot be read
```
cause The paths provided for `pfxPath`, `certPath`, or `keyPath` are incorrect, or the process lacks read permissions for the specified files.

fix Verify that the file paths are correct and absolute, and that the Node.js process has the necessary permissions to access the certificate files.
```
Authentication failed: Error: Page load timeout exceeded
```
cause The page specified by the `url` option took longer than the default 30 seconds (or custom `timeout`) to load after the certificate was provided.

fix Increase the `timeout` option in the `CertificateAuthSession` constructor for pages with longer loading times, or debug network issues/authentication flow if the page genuinely isn't loading.

Warnings

breaking As a pre-1.0.0 package (currently 0.0.3), the API surface is subject to change without strict adherence to SemVer, potentially introducing breaking changes in minor or patch releases.
Fix: Refer to the latest README or GitHub releases for any changes when updating the package.
gotcha Playwright itself introduced native client certificate support in version 1.46. While this package simplifies the process, direct Playwright configuration might offer more flexibility or be preferred for complex scenarios.
Fix: Consider using Playwright's `clientCertificates` option in `use` block of `playwright.config.ts` for native integration if this package's abstraction is not precisely what's needed.
gotcha Handling sensitive certificate passphrases and paths requires careful environment management. Hardcoding them is a security risk.
Fix: Always use environment variables (e.g., `process.env.PFX_PASSPHRASE`) or a secure secret management system to inject certificate credentials at runtime.
gotcha Client certificate authentication can sometimes still trigger a manual certificate selection pop-up in the browser, even with programmatic configuration, depending on the browser, OS, and specific server configuration.
Fix: Ensure that the `origin` specified exactly matches the server's certificate request origin. Test thoroughly in different browser environments. In some stubborn cases, manual interaction might be unavoidable or a different approach (like using an authentication proxy) might be necessary.

Install

npm install playwright-client-certificate-login npm
yarn add playwright-client-certificate-login yarn
pnpm add playwright-client-certificate-login pnpm

Imports

CertificateAuthSession

wrong:

const CertificateAuthSession = require('playwright-client-certificate-login').CertificateAuthSession;

correct:

import { CertificateAuthSession } from 'playwright-client-certificate-login';

The README primarily shows CommonJS `require`. For modern Node.js and TypeScript projects, prefer ESM `import` as shown.

Quickstart

Demonstrates authenticating to a web application using a PFX client certificate, capturing cookies, headers, and taking a screenshot of the authenticated page.

import { CertificateAuthSession } from 'playwright-client-certificate-login';
import path from 'path';

async function authenticateWithCert() {
  const pfxPath = process.env.PFX_CERT_PATH ?? path.resolve(__dirname, './your-certificate.pfx');
  const passphrase = process.env.CERT_PASSPHRASE ?? 'your-certificate-passphrase';

  if (!pfxPath || !passphrase) {
    console.error('Environment variables PFX_CERT_PATH and CERT_PASSPHRASE must be set, or provide hardcoded defaults.');
    return;
  }

  const options = {
    origin: 'https://your-secure-domain.com',
    url: 'https://your-secure-domain.com/dashboard',
    pfxPath: pfxPath,
    passphrase: passphrase
  };

  const session = new CertificateAuthSession(options);
  try {
    console.log('Attempting authentication...');
    await session.authenticate();

    const cookies = await session.getCookies();
    const headers = session.getHeaders();
    console.log('Authentication successful. Cookies:', cookies.map(c => c.name));
    console.log('Prepared Headers:', headers);

    // Example: Interact with the authenticated page
    const page = session.getPage();
    await page.screenshot({ path: 'authenticated-dashboard.png' });
    console.log('Screenshot taken: authenticated-dashboard.png');

  } catch (error) {
    console.error('Authentication failed:', error);
  } finally {
    console.log('Closing browser session.');
    await session.close();
  }
}

authenticateWithCert();

view raw JSON →