mTLS in Node.js: Certificati Client in 12 Passi [2026]

Nota la durata più breve per il certificato client (365 giorni contro 825 per il server): più un'identità è granulare e distribuita, più conviene tenerla a scadenza breve, per limitare i danni in caso di chiave compromessa. Ripeti questo passo per ogni client che deve poter parlare con la tua API, usando un CN diverso per ciascuno: questo ti permette in seguito di distinguere e revocare le identità singolarmente.

Passo 5: configura il server HTTPS in Node.js con mTLS

Con i certificati pronti, il server Node.js richiede tre opzioni fondamentali sull'oggetto passato a https.createServer: cert e key per l'identità del server, ca per la lista di CA fidate contro cui validare i certificati client, requestCert: true per chiedere effettivamente un certificato, e rejectUnauthorized: true per rifiutare chi non lo presenta o lo presenta non valido.

// server.js
const https = require('https');
const fs = require('fs');
const express = require('express');

const app = express();

app.get('/api/dati', (req, res) => {
  const cert = req.socket.getPeerCertificate();
  res.json({
    messaggio: 'Accesso autorizzato via mTLS',
    clientCN: cert.subject && cert.subject.CN
  });
});

const options = {
  key: fs.readFileSync('server/server-key.pem'),
  cert: fs.readFileSync('server/server-cert.pem'),
  ca: [fs.readFileSync('ca/ca-cert.pem')],
  requestCert: true,
  rejectUnauthorized: true
};

https.createServer(options, app).listen(8443, () => {
  console.log('Server mTLS in ascolto su https://localhost:8443');
});

Con rejectUnauthorized: true, Node.js chiude la connessione a livello TLS prima ancora che Express veda la richiesta se il certificato client non è firmato da una delle CA elencate in ca. È il comportamento corretto per la maggior parte dei casi, ma non basta da solo: verifica sempre anche i campi del certificato a livello applicativo, come mostrato nel passo successivo.

Passo 6: valida Key Usage ed Extended Key Usage (la lezione di CVE-2026-45389)

Il caso OCaml-TLS ha dimostrato un punto sottile: un certificato firmato da una CA fidata, con catena di trust valida, può comunque essere il certificato "sbagliato" se non ha l'Extended Key Usage clientAuth. Molte implementazioni si fermano al controllo "la CA lo ha firmato, quindi va bene", senza controllare per cosa quel certificato era stato emesso. Node.js non fa questa verifica in automatico: va aggiunta esplicitamente.

const crypto = require('crypto');

function verificaClientAuth(pemCert) {
  const x509 = new crypto.X509Certificate(pemCert);
  const eku = x509.extKeyUsage || [];
  // OID 1.3.6.1.5.5.7.3.2 corrisponde a clientAuth
  if (!eku.includes('1.3.6.1.5.5.7.3.2')) {
    throw new Error('Certificato privo di Extended Key Usage clientAuth');
  }
  return true;
}

app.use((req, res, next) => {
  const cert = req.socket.getPeerCertificate();
  if (!cert || !cert.raw) {
    return res.status(401).json({ errore: 'Certificato client mancante' });
  }
  try {
    const pem = '-----BEGIN CERTIFICATE-----\n' +
      cert.raw.toString('base64').match(/.{1,64}/g).join('\n') +
      '\n-----END CERTIFICATE-----';
    verificaClientAuth(pem);
    next();
  } catch (err) {
    res.status(403).json({ errore: err.message });
  }
});

Questo middleware usa la classe crypto.X509Certificate, disponibile in Node.js dalla versione 15.6 e stabile nelle release LTS più recenti, per leggere l'attributo extKeyUsage direttamente dal certificato presentato in connessione. Se manca l'OID di clientAuth, la richiesta viene rifiutata con 403 prima di raggiungere qualsiasi route applicativa. È lo stesso controllo che, se presente in OCaml-TLS prima della versione 2.1.0, avrebbe impedito lo scenario descritto in CVE-2026-45389.

Passo 7: scrivi il client Node.js che presenta il certificato

Sul lato client, la libreria nativa https accetta le stesse tre credenziali (chiave privata, certificato, CA) passate come opzioni della richiesta. Se il certificato del server non è firmato da una CA pubblica riconosciuta (come nel caso di un ambiente interno con CA privata), va indicata esplicitamente anche la CA con cui validare il server.

// client.js
const https = require('https');
const fs = require('fs');

const options = {
  hostname: 'localhost',
  port: 8443,
  path: '/api/dati',
  method: 'GET',
  key: fs.readFileSync('client/client-key.pem'),
  cert: fs.readFileSync('client/client-cert.pem'),
  ca: [fs.readFileSync('ca/ca-cert.pem')]
};

const req = https.request(options, (res) => {
  let body = '';
  res.on('data', (chunk) => { body += chunk; });
  res.on('end', () => console.log('Risposta:', body));
});

req.on('error', (err) => console.error('Errore connessione:', err.message));
req.end();

Eseguendo node server.js in un terminale e node client.js in un altro, l'output atteso è:

Risposta: {"messaggio":"Accesso autorizzato via mTLS","clientCN":"client-fatturazione-01"}

Se rimuovi temporaneamente cert e key dalle opzioni del client e riesegui la richiesta, la connessione fallisce già durante l'handshake TLS con un errore del tipo ECONNRESET lato client e UNABLE_TO_VERIFY_LEAF_SIGNATURE o simile lato server: è la prova che l'autenticazione avviene prima che Express veda anche solo un header della richiesta.

Passo 8: gestisci la revoca con CRL e OCSP (la lezione di CVE-2026-34500)

Emettere certificati è la parte facile. Revocarli quando un dipendente lascia l'azienda, un servizio viene dismesso o una chiave privata finisce in un repository pubblico è dove molte implementazioni mTLS falliscono in silenzio, come ha mostrato CVE-2026-34500 in Tomcat: il controllo OCSP poteva fallire "in soft" (accettando comunque il certificato) anche quando l'amministratore aveva esplicitamente disattivato quel comportamento.

Il meccanismo più semplice da implementare in proprio è una Certificate Revocation List: un elenco di numeri seriali di certificati non più validi, che il server consulta a ogni handshake.

# Genera la CRL iniziale (vuota)
openssl ca -config ca/ca.cnf -gencrl -out ca/ca-crl.pem

# Revoca un certificato compromesso
openssl ca -config ca/ca.cnf -revoke client/client-cert-compromesso.pem

# Rigenera la CRL dopo ogni revoca
openssl ca -config ca/ca.cnf -gencrl -out ca/ca-crl.pem

In Node.js la CRL va caricata insieme alla CA, passandola come opzione crl di https.createServer: il motore TLS nativo la consulta automaticamente e rifiuta i certificati il cui numero seriale compare nella lista. Il punto critico, esattamente quello aggirato in Tomcat, è decidere cosa succede quando la CRL non è raggiungibile o non aggiornata: la scelta corretta per ambienti sensibili è il fail-closed, cioè rifiutare la connessione se la CRL non può essere verificata, invece di accettarla "per non bloccare il servizio". Rigenera e ridistribuisci la CRL su un ciclo automatico (ogni ora o ogni giorno, a seconda della sensibilità del sistema) invece di farlo manualmente dopo un incidente.

Passo 9: registra e monitora le connessioni mTLS

Un'identità basata su certificato è più utile di un token anche a scopo di audit: ogni richiesta può essere associata a un CN specifico, non solo a un indirizzo IP o a una chiave API condivisa da più client. Aggiungi un logging strutturato che registri l'identità del chiamante a ogni richiesta.

app.use((req, res, next) => {
  const cert = req.socket.getPeerCertificate();
  const logEntry = {
    timestamp: new Date().toISOString(),
    clientCN: cert.subject ? cert.subject.CN : 'sconosciuto',
    serial: cert.serialNumber,
    validoFino: cert.valid_to,
    metodo: req.method,
    percorso: req.path,
    ip: req.socket.remoteAddress
  };
  console.log(JSON.stringify(logEntry));
  next();
});

In produzione questi log vanno inviati a un sistema centralizzato (Wazuh, un SIEM, o anche solo un aggregatore come Loki) per poter correlare tentativi di accesso con certificati scaduti, revocati o con CN inattesi. Un picco improvviso di connessioni rifiutate per certificato scaduto, ad esempio, è spesso il primo segnale che un job di rotazione automatica si è fermato senza che nessuno se ne accorgesse.

Passo 10: automatizza la rotazione dei certificati

Certificati client con validità di un anno significano che, prima o poi, qualcuno dimenticherà di rinnovarli, e un servizio smetterà di funzionare nel weekend sbagliato. Lo script seguente calcola i giorni residui prima della scadenza e genera un avviso quando si scende sotto una soglia, da integrare in un cron job o in una pipeline CI/CD.

#!/usr/bin/env node
const { execSync } = require('child_process');

const SOGLIA_GIORNI = 30;
const certificati = ['server/server-cert.pem', 'client/client-cert.pem'];

certificati.forEach((percorso) => {
  const output = execSync(`openssl x509 -enddate -noout -in ${percorso}`).toString();
  const scadenza = new Date(output.replace('notAfter=', '').trim());
  const giorniResidui = Math.floor((scadenza - new Date()) / (1000 * 60 * 60 * 24));

  if (giorniResidui <= SOGLIA_GIORNI) {
    console.warn(`ATTENZIONE: ${percorso} scade tra ${giorniResidui} giorni`);
    process.exitCode = 1;
  } else {
    console.log(`${percorso} valido ancora ${giorniResidui} giorni`);
  }
});

Pianifica questo controllo con una frequenza giornaliera e collegalo a un canale di notifica (email, Slack, o il tuo sistema di ticketing). Per ambienti più maturi, vale la pena valutare uno strumento dedicato alla gestione del ciclo di vita dei certificati, come step-ca di Smallstep, che automatizza sia l'emissione sia il rinnovo senza intervento manuale.

Passo 11: metti mTLS dietro un reverse proxy Nginx

In molte architetture, la terminazione TLS non avviene direttamente nel processo Node.js ma su un reverse proxy che poi inoltra il traffico all'applicazione. Nginx supporta l'mTLS in modo nativo con poche direttive, e può anche passare l'identità del client all'applicazione tramite header, se la connessione interna resta su rete fidata.

server {
    listen 443 ssl;
    server_name api.esempio.local;

    ssl_certificate     /etc/nginx/certs/server-cert.pem;
    ssl_certificate_key /etc/nginx/certs/server-key.pem;

    ssl_client_certificate /etc/nginx/certs/ca-cert.pem;
    ssl_verify_client on;
    ssl_crl /etc/nginx/certs/ca-crl.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header X-Client-CN $ssl_client_s_dn_cn;
        proxy_set_header X-Client-Verify $ssl_client_verify;
    }
}

Con questa configurazione, Nginx fa da guardiano: rifiuta le connessioni senza certificato valido prima ancora che raggiungano Node.js, e passa l'identità verificata come header X-Client-CN. L'applicazione Node.js a quel punto può fidarsi dell'header solo se il canale tra Nginx e Node.js è protetto (localhost, rete privata, o mTLS interno): esporre quella porta interna direttamente su internet vanificherebbe tutta la protezione a monte.

Passo 12: testa tutto end-to-end, il progetto completo

A questo punto la struttura del progetto dovrebbe assomigliare a questa, con tutti i file generati nei passi precedenti:

mtls-project/
├── ca/
│   ├── ca-key.pem
│   ├── ca-cert.pem
│   └── ca-crl.pem
├── server/
│   ├── server-key.pem
│   ├── server-cert.pem
│   └── server-ext.cnf
├── client/
│   ├── client-key.pem
│   ├── client-cert.pem
│   └── client-ext.cnf
├── server.js
├── client.js
├── check-scadenze.js
└── package.json

Esegui la sequenza di test completa: avvia il server con node server.js, verifica con un client legittimo (node client.js, output atteso: risposta 200 con il CN corretto), poi ripeti il test con un certificato scaduto, uno emesso da una CA diversa e uno privo di clientAuth nell'Extended Key Usage. In tutti e tre i casi la connessione deve essere rifiutata, con messaggi di errore diversi a seconda del punto in cui fallisce la verifica (handshake TLS per CA sbagliata o certificato scaduto, middleware applicativo per EKU mancante). Solo quando tutti e quattro gli scenari si comportano come previsto il sistema è pronto per un ambiente di staging.

Verifica la configurazione con curl e openssl s_client prima di scrivere codice client

Prima ancora di scrivere un client Node.js, conviene verificare che server e certificati funzionino con strumenti da riga di comando: se qualcosa non torna a questo livello, il problema è nei certificati, non nel codice applicativo. curl supporta nativamente mTLS con tre flag.

# Richiesta autenticata con certificato client
curl --cert client/client-cert.pem --key client/client-key.pem \
  --cacert ca/ca-cert.pem https://localhost:8443/api/dati

# Stesso test, ma senza certificato client: deve fallire
curl --cacert ca/ca-cert.pem https://localhost:8443/api/dati

La prima richiesta deve restituire il JSON con il CN del client, la seconda deve fallire con un errore del tipo curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL oppure un rifiuto esplicito della connessione, a seconda della versione di OpenSSL installata sul sistema. Per ispezionare l'intero handshake, incluso il certificato presentato dal server e la catena di validazione, openssl s_client resta lo strumento più dettagliato:

openssl s_client -connect localhost:8443 \
  -cert client/client-cert.pem -key client/client-key.pem \
  -CAfile ca/ca-cert.pem -state -brief

Nell'output cerca la riga Verification: OK: se compare invece Verify return code con un numero diverso da zero, la causa è quasi sempre una CA sbagliata, un certificato scaduto o una catena di firma incompleta. Questo passaggio di verifica manuale, spesso saltato per fretta, avrebbe permesso di individuare in fase di test comportamenti come quello di CVE-2026-34500: bastava osservare che la verifica riportava un esito positivo anche con un certificato che avrebbe dovuto essere rifiutato per revoca.

mTLS vs API Key vs OAuth Bearer vs JWT: quale scegliere

Nessuno di questi meccanismi è universalmente "migliore": la scelta dipende da chi deve autenticarsi (utenti umani o macchine) e da quanto è sensibile il canale.

Nella pratica, le architetture più mature combinano più livelli: mTLS per proteggere il canale di trasporto tra servizi interni, e un JWT o un token OAuth applicativo sopra quel canale per portare informazioni su permessi e scope. L'OWASP API Security Project colloca l'autenticazione debole tra le categorie di rischio più ricorrenti per le API (OWASP API Security Top 10), e l'mTLS affronta esattamente quella categoria alla radice, spostando la verifica di identità dal livello applicativo al livello di trasporto. Se stai già proteggendo un API gateway con altre tecniche, la nostra guida a API Gateway sicuro in Node.js e l'analisi delle vulnerabilità OWASP Top 10 in Node.js sono un buon complemento a questo tutorial.

Errori comuni da evitare

Questi sono gli errori più frequenti osservati in implementazioni mTLS reali, spesso responsabili di falle silenti che passano inosservate per mesi.

Risoluzione dei problemi più comuni

Ecco i problemi che si incontrano più spesso durante l'implementazione, con la causa più probabile e la soluzione. Se il tuo errore non compare in questa lista, il primo passo di diagnosi resta sempre lo stesso: isola il problema con openssl s_client prima di sospettare del codice Node.js, così sai se il difetto è nella catena di certificati o nella logica applicativa.

• Errore "UNABLE_TO_VERIFY_LEAF_SIGNATURE": il client non ha ricevuto o non sta usando il certificato della CA corretta nell'opzione ca. Verifica che il percorso del file sia giusto e che il certificato caricato corrisponda a quello usato per firmare il certificato del server.
• Connessione chiusa con "ECONNRESET" appena avviata: il server ha requestCert: true ma il client non presenta alcun certificato. Controlla che cert e key siano effettivamente impostati nelle opzioni della richiesta client.
• "ERR_OSSL_X509_KEY_VALUES_MISMATCH": la chiave privata caricata non corrisponde al certificato. Succede spesso dopo aver rigenerato un certificato senza rigenerare anche la chiave, o mischiando file di ambienti diversi.
• Il server accetta certificati che dovrebbero essere scaduti: l'orologio di sistema del server è desincronizzato. Verifica NTP: OpenSSL e Node.js si fidano dell'orario locale della macchina per valutare la validità temporale del certificato.
• Il campo cert.subject.CN risulta undefined nel middleware: probabile che rejectUnauthorized sia impostato su false, nel qual caso Node.js consente comunque la connessione ma popola in modo incompleto l'oggetto certificato.
• Nginx risponde 400 "No required SSL certificate was sent": la direttiva ssl_verify_client è impostata su on ma il client non ha certificato. Se alcuni endpoint devono restare pubblici, usa ssl_verify_client optional e verifica $ssl_client_verify nella logica applicativa.
• La CRL non viene mai consultata dal server Node.js: manca l'opzione crl in https.createServer, oppure il file CRL non è nel formato PEM atteso. Verifica con openssl crl -in ca-crl.pem -text -noout che il file sia leggibile.
• Le performance calano sensibilmente con molte connessioni simultanee: l'handshake mTLS è più costoso di un handshake TLS standard per via della verifica aggiuntiva del certificato client. Valuta il riuso delle sessioni TLS (session resumption) e, per volumi alti, la terminazione a livello di load balancer con hardware o istanze dedicate.

Consigli avanzati per produzione e conformità in Europa

Una volta superato il prototipo, alcune scelte fanno la differenza tra un mTLS che regge in produzione e uno che diventa un incubo operativo. Primo: automatizza l'intero ciclo di vita dei certificati con un protocollo come ACME (lo stesso di Let's Encrypt, adattabile a CA interne) o uno strumento dedicato, invece di script artigianali eseguiti manualmente. Vale anche la pena combinare mTLS con l'hardening dell'accesso SSH ai server che ospitano la CA: la nostra guida a chiavi SSH Ed25519 e hardening server copre esattamente questo scenario. Secondo: separa sempre la CA "root" da una CA "intermedia" che firma i certificati operativi, così la root può restare offline quasi permanentemente, riducendo drasticamente la superficie di attacco sulla chiave più critica del sistema.

Terzo, per chi opera in settori toccati da NIS2 (energia, sanità, finanza, infrastrutture digitali), documenta la gerarchia dei certificati e le procedure di revoca come parte del piano di risposta agli incidenti: un audit chiederà quasi certamente come viene gestita la compromissione di un'identità macchina-a-macchina, e "revochiamo manualmente quando ce ne accorgiamo" non è una risposta che regge. Quarto, tieni d'occhio la roadmap di Node.js: la versione 26.x diventerà LTS a ottobre 2026, estendendo il supporto TLS fino al 2029, e pianificare la migrazione con un anno di anticipo evita di trovarsi a gestire mTLS su una versione di Node.js fuori supporto proprio mentre esce una nuova falla nello stack TLS.

Infine, se l'infrastruttura cresce verso decine di microservizi, valuta un service mesh (Istio, Linkerd) che gestisce l'mTLS interno automaticamente tra sidecar, riservando l'implementazione manuale descritta in questa guida ai punti di ingresso esposti a client esterni, dove il controllo granulare rimane indispensabile.

Quando mTLS non è la scelta giusta

Non tutte le API hanno bisogno di mTLS, e forzarlo dove non serve aggiunge solo complessità operativa senza un beneficio proporzionato. Per API pubbliche rivolte a sviluppatori esterni con centinaia o migliaia di integrazioni, gestire un certificato per ciascun client diventa rapidamente un collo di bottiglia: emissione, distribuzione sicura della chiave privata e supporto quando qualcosa va storto richiedono un processo che poche organizzazioni hanno la capacità di scalare. In questi casi, OAuth 2.0 con rotazione frequente dei token o chiavi API abbinate a rate limiting aggressivo restano scelte più pratiche.

Lo stesso vale per applicazioni consumer con utenti finali su browser o app mobile: distribuire e proteggere un certificato client su un dispositivo controllato dall'utente, e non dall'organizzazione, introduce problemi di gestione che raramente giustificano il beneficio rispetto a un buon sistema di autenticazione a più fattori. mTLS rende il massimo quando entrambe le parti della connessione sono sistemi che l'organizzazione controlla direttamente: server interni, microservizi, integrazioni B2B con partner con cui esiste già un rapporto contrattuale che permette lo scambio sicuro di certificati.

Domande frequenti

Che differenza c'è tra TLS e mTLS?

Nel TLS classico solo il server dimostra la propria identità con un certificato. Nell'mTLS anche il client deve presentare un certificato X.509, verificato dal server prima di stabilire la connessione: l'autenticazione diventa bidirezionale invece che a senso unico.

mTLS sostituisce OAuth 2.0 o i JWT?

No, li completa. mTLS protegge il canale di trasporto e l'identità della macchina o del servizio che si connette. OAuth e JWT gestiscono permessi, scope e deleghe a livello applicativo. Molte architetture usano entrambi insieme.

Quanto deve durare un certificato client in produzione?

Non esiste un numero universale, ma la tendenza è verso durate sempre più brevi (settimane o pochi mesi) combinate con rinnovo automatico, per limitare la finestra di esposizione in caso di chiave privata compromessa.

Cosa succede se il certificato client scade durante una connessione attiva?

Una connessione TLS già stabilita non viene interrotta automaticamente alla scadenza: la verifica avviene durante l'handshake iniziale. È quindi importante monitorare le scadenze e rinnovare i certificati prima che il client debba stabilire una nuova connessione.

È obbligatorio usare una CA interna, o si può usare una CA pubblica anche per i client?

Per i certificati client, quasi sempre conviene una CA interna: le CA pubbliche sono pensate per identificare server pubblici (domini), non identità interne come "servizio-fatturazione" o "client-partner-01". Una CA interna dà pieno controllo su emissione e revoca.

mTLS funziona con i browser web?

Sì, i browser moderni supportano i certificati client, ma l'esperienza utente (selezione manuale del certificato, gestione dell'importazione) lo rende poco pratico per utenti finali generici. È molto più diffuso per comunicazioni machine-to-machine, API B2B e microservizi, dove il certificato viene distribuito e gestito centralmente dal team IT invece che dall'utente stesso.

Che impatto ha mTLS sulle performance rispetto a HTTPS normale?

L'handshake iniziale è leggermente più costoso per via della verifica aggiuntiva del certificato client, ma con il riuso delle sessioni TLS l'impatto sulle richieste successive è marginale nella maggior parte dei carichi di lavoro reali.