client-certificate-auth API Reference

---

client-certificate-auth API Reference / extractor / extractClientCertificate

Function: extractClientCertificate()

extractClientCertificate(req, options?): ExtractionResult

Defined in: extractor.js:211

Extract client certificate from request.

Works with both header-based extraction (reverse proxy scenarios) and socket-based extraction (direct TLS connections). Returns a structured result object instead of throwing or using callbacks, making it suitable for any framework adapter.

Parameters

req

Request object with headers and optional socket. A missing or non-object headers field, one whose accessor throws, and one holding a property whose accessor throws are all treated as having no headers.

headers?

Record<string, string | string[] | undefined>

HTTP headers object

rawHeaders?

string[]

Node's raw header list; a certificate or verification header that appears more than once is rejected

socket?

{ authorized?: boolean; getPeerCertificate?: (detailed) => PeerCertificate; }

TLS socket with getPeerCertificate() method

socket.authorized?

boolean

Whether socket was authorized

socket.getPeerCertificate?

(detailed) => PeerCertificate

Get peer certificate

options?

ExtractorOptions = {}

Extraction options

Returns

ExtractionResult

Examples

// AWS ALB header extraction
const result = extractClientCertificate(req, { certificateSource: 'aws-alb' });
if (result.success) {
  console.log('Certificate CN:', result.certificate.subject.CN);
} else {
  console.error('Extraction failed:', result.reason);
}

// Socket extraction with fallback
const result = extractClientCertificate(req, {
  certificateSource: 'envoy',
  fallbackToSocket: true
});