Come installare un certificato SSL in Tomcat

In questo tutorial imparerai come installare un certificato SSL su Apache Tomcat utilizzando l’utility Java keytool, per poi configurare il connettore HTTPS nel file server.xml. Se non hai ancora generato la tua CSR, la prima sezione ti mostra come farlo.

Abbiamo anche registrato un video che ti guida attraverso l’intero processo. Puoi guardare il video, leggere le istruzioni, oppure fare entrambe le cose. Puoi guardare il video qui sotto.

Genera un codice CSR per Tomcat

CSR è l’acronimo di Certificate Signing Request, un blocco di testo contenente i dettagli attuali sul tuo dominio e sulla tua organizzazione. Ogni acquirente di un certificato SSL commerciale deve inviare una CSR alla Certificate Authority (il fornitore SSL) per superare la validazione e ricevere il certificato. Se la CSR contiene dettagli errati, la CA non la firmerà.

Su Tomcat, la CSR viene creata con keytool a partire da un keystore Java, e quello stesso keystore contiene la chiave privata che riutilizzerai durante l’installazione. Hai due opzioni:

• Usa il nostro Generatore di CSR per creare la CSR automaticamente.
• Segui il nostro tutorial passo dopo passo su come generare una CSR su Tomcat.

Importante: tieni traccia del file keystore e dell’alias utilizzato durante la generazione della CSR. Importerai nuovamente il tuo certificato firmato in quello stesso alias in seguito, poiché è lì che si trova la chiave privata corrispondente.

Dopo che la Certificate Authority ha validato la tua richiesta e ti ha inviato i file SSL, continua con l’installazione descritta di seguito.

Installa un certificato SSL su Tomcat

Un’installazione su Tomcat prevede due fasi: prima importi la catena di certificati e il tuo certificato firmato nel keystore che contiene già la tua chiave privata, poi configuri il connettore HTTPS nel file server.xml affinché utilizzi quel keystore.

Fase 1: Prepara i file del certificato SSL

La tua Certificate Authority invia i file all’indirizzo email che hai fornito, di solito come archivio ZIP. Estrailo. In base alla CA, i file arrivano in uno di questi due formati:

• PKCS#7: un unico file .p7b (o .cer) che già raggruppa il tuo certificato insieme al certificato root e ai certificati intermedi.
• PEM: file separati, tipicamente un file .crt per il certificato del server più singoli file root.crt e intermediate.crt.

Carica i file estratti sul server, nella stessa directory del keystore da cui hai generato la CSR (indicato di seguito come example.jks). Identifica il tuo formato e segui le istruzioni corrispondenti.

Hai generato la CSR altrove, quindi la tua chiave privata è un file separato piuttosto che una voce in example.jks? Salta keytool: converti PEM in PKCS#12 per raggruppare il certificato, la catena e la chiave in un unico file .p12, poi fai riferimento a quel file nella Fase 3 con certificateKeystoreType=”PKCS12″.

Fase 2: Importa il certificato nel tuo keystore

Formato PKCS#7. Poiché un file .p7b contiene già l’intera catena, un unico comando importa tutto in una sola volta, nel tuo alias già esistente per la chiave privata:

keytool -import -trustcacerts -alias ssldragon -keystore example.jks -file example.p7b

Sostituisci ssldragon con il tuo alias e example con i nomi dei tuoi file. L’alias deve essere quello che contiene già la tua chiave privata (l’alias usato nella fase della CSR). Quando vedi il messaggio Certificate reply was installed in keystore, l’importazione è riuscita. Verifica il contenuto del keystore con:

keytool -list -v -keystore example.jks

Cerca una voce il cui tipo sia PrivateKeyEntry con una lunghezza della catena di certificati superiore a 1. Ciò confirma che il certificato firmato è ora associato alla tua chiave privata.

Formato PEM. Importa i certificati separatamente, nell’ordine della catena: prima il root, poi eventuali certificati intermedi, e per ultimo il tuo certificato di dominio. Importare prima la catena permette a keytool di costruire un percorso di attendibilità completo prima di associare la risposta alla tua chiave. Importa il certificato root:

keytool -import -trustcacerts -alias root -keystore example.jks -file root.crt

Poi importa il certificato intermedio:

keytool -import -trustcacerts -alias intermediate -keystore example.jks -file intermediate.crt

Se la tua CA fornisce più certificati intermedi, importa ciascuno con il proprio alias di attendibilità, seguendo l’ordine con cui si firmano a vicenda (dal root fino al certificato di dominio). Ad esempio, un certificato Sectigo PositiveSSL viene fornito con più di un certificato intermedio, quindi importali in sequenza prima del certificato di dominio.

Infine, importa il tuo certificato principale (quello rilasciato per il tuo dominio) nell’alias esistente della chiave privata, lo stesso alias usato durante la generazione della CSR:

keytool -import -trustcacerts -alias ssldragon -keystore example.jks -file example.crt

Qui, ssldragon deve essere il tuo alias esistente della chiave privata. Poiché quell’alias possiede già una chiave, keytool tratta questa importazione come una certificate reply e associa il certificato firmato alla chiave. È questo il passaggio che fa funzionare HTTPS.

Errore critico da evitare: non importare il certificato firmato con un alias completamente nuovo. Se l’alias non possiede una chiave privata esistente, keytool memorizza il certificato come voce di attendibilità autonoma senza alcuna chiave associata, e TLS non funzionerà. Se non sei sicuro di quale alias contenga la tua chiave, esegui keytool -list -v -keystore example.jks e usa l’alias il cui tipo è PrivateKeyEntry.

Fase 3: Configura il connettore HTTPS nel file server.xml

Con il certificato nel tuo keystore, fai puntare il connettore HTTPS di Tomcat verso di esso. Il connettore è definito nel file server.xml, situato nella cartella conf della tua installazione di Tomcat (ad esempio $CATALINA_HOME/conf/server.xml). Apri il file in un editor di testo.

Nelle versioni attuali di Tomcat (9, 10 e 11), la forma consigliata annida un elemento SSLHostConfig, che a sua volta contiene un elemento Certificate che fa riferimento al tuo keystore. Aggiungi o aggiorna il connettore sicuro in questo modo:

<Connector
    port="443"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    maxThreads="150"
    SSLEnabled="true"
    scheme="https"
    secure="true">
  <SSLHostConfig>
    <Certificate
        certificateKeystoreFile="/your_path/example.jks"
        certificateKeystorePassword="your_keystore_password"
        certificateKeystoreType="JKS"
        certificateKeyAlias="ssldragon"
        type="RSA" />
  </SSLHostConfig>
</Connector>

• certificateKeystoreFile: il percorso completo del tuo file keystore.
• certificateKeystorePassword: la password del keystore.
• certificateKeystoreType: JKS per un keystore .jks, oppure PKCS12 per un keystore .p12 / .pfx.
• certificateKeyAlias: l’alias che contiene la tua chiave privata e il certificato firmato (qui, ssldragon). Questo indica a Tomcat quale voce servire quando il keystore contiene più di una voce.

Nota: la porta 443 è la porta HTTPS standard utilizzata sopra; gli esempi predefiniti di Tomcat usano invece la porta 8443, quindi usa quella prevista dal tuo ambiente. Se questa è la tua prima configurazione HTTPS, il connettore sicuro potrebbe essere commentato nel file server.xml. Rimuovi i marcatori di commento che lo circondano affinché il connettore sia attivo, e assicurati che nessun altro connettore sia già associato alla stessa porta.

Forma legacy (Tomcat più vecchi). Le guide più datate collocano i dettagli del keystore direttamente sul connettore come attributi keystoreFile e keystorePass. Questo stile è stato sostituito dagli elementi SSLHostConfig e Certificate mostrati sopra, che è la forma da usare nelle versioni di Tomcat supportate.

Fase 4: Salva server.xml e riavvia Tomcat

Salva server.xml, poi riavvia Tomcat affinché ricarichi la configurazione. Su Linux, usa gli script inclusi:

$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh

Se Tomcat viene eseguito come servizio, riavvialo invece tramite il tuo gestore di servizi (ad esempio systemctl restart tomcat su Linux, oppure il pannello Servizi su Windows). Congratulazioni, il tuo certificato SSL è ora installato sul tuo server Tomcat.

Testa la tua installazione SSL su Tomcat

Dopo aver installato il certificato, piccoli errori possono passare inosservati e influire sul modo in cui i browser trattano il tuo sito. Fai in modo di verificare regolarmente l’installazione. Esegui il nostro SSL Checker per una scansione istantanea che rileva problemi come un certificato intermedio mancante o una catena non attendibile.

Domande Frequenti