Implementation:Microsoft Playwright SocksClientCertificatesInterceptor

Knowledge Sources	Microsoft_Playwright
Domains	TLS Security, Client Certificates
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for injecting client TLS certificates via a SOCKS5 proxy provided by the Playwright library.

Description

The `ClientCertificatesProxy` class implements client certificate injection for browser connections using a SOCKS5 proxy approach. Instead of patching each browser's TLS stack, Playwright routes browser traffic through a local SOCKS5 proxy that performs TLS handshakes with the target servers using the specified client certificates. The class handles two distinct flows: HTTP (plain text, direct pipe) and HTTPS (TLS interception with re-encryption). For HTTPS, it performs a first-byte check (0x16 = TLS handshake) to distinguish between HTTP and HTTPS traffic, then establishes a TLS connection to the real server with the client certificate while presenting a self-signed dummy certificate to the browser. It supports HTTP/2 via `http2.createSecureServer` and includes ALPNProtocol negotiation.

Usage

Use this class when browser tests require client TLS certificates for authentication. It is automatically set up by `BrowserType` when `clientCertificates` are specified in the browser context options.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/server/socksClientCertificatesInterceptor.ts

Signature

export class ClientCertificatesProxy {
  private _socksProxy: SocksProxy;
  private _sockets: Map<string, net.Socket>;

  constructor(
    parent: SdkObject,
    clientCertificates: types.BrowserContextOptions['clientCertificates'],
    contextOptions: types.BrowserContextOptions
  );

  async listen(): Promise<string>;
  async close(): Promise<void>;
}

Import

import { ClientCertificatesProxy } from '../server/socksClientCertificatesInterceptor';

I/O Contract

Inputs

Name	Type	Required	Description
parent	SdkObject	Yes	Parent SDK object for instrumentation
clientCertificates	types.BrowserContextOptions['clientCertificates']	Yes	Array of client certificate configurations (origin, certPath, keyPath, pfxPath, passphrase)
contextOptions	types.BrowserContextOptions	Yes	Browser context options including ignoreHTTPSErrors setting

Outputs

Name	Type	Description
proxyAddress	string	SOCKS5 proxy address (host:port) to configure the browser with

Usage Examples

import { ClientCertificatesProxy } from 'playwright-core/lib/server/socksClientCertificatesInterceptor';

const certProxy = new ClientCertificatesProxy(parentSdk, [
  {
    origin: 'https://secure.example.com',
    certPath: '/path/to/client.crt',
    keyPath: '/path/to/client.key',
  }
], contextOptions);

const proxyAddress = await certProxy.listen();
// Browser is configured to use this SOCKS5 proxy
// All traffic to matching origins will include the client certificate

await certProxy.close();

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment