Come installare un certificato SSL in Tomcat

In questo tutorial imparerai come installare un certificato SSL su Apache Tomcat utilizzando lo strumento Java keytool, per poi configurare il connettore HTTPS in server.xml. Se non hai ancora generato il tuo CSR, la prima sezione ti mostra come fare.

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

Generare un codice CSR per Tomcat

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

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

• Usa il nostro Generatore CSR per creare il CSR automaticamente.
• Segui il nostro tutorial passo-passo su come generare un CSR su Tomcat.

Importante: tieni traccia del file keystore e dell’alias utilizzato durante la generazione del CSR. Importerai successivamente il tuo certificato firmato esattamente in quell’alias, poiché è lì che risiede la chiave privata corrispondente.

Dopo che la Certificate Authority ha convalidato la tua richiesta e ti ha inviato i file SSL, prosegui con l’installazione qui sotto.

Installare 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 già contiene la tua chiave privata, poi configuri il connettore HTTPS in server.xml affinché utilizzi quel keystore.

Passo 1: Prepara i file del tuo certificato SSL

La tua Certificate Authority invia i file tramite email all’indirizzo fornito, di solito come archivio ZIP. Estrailo. A seconda della CA, i file arrivano in uno dei due formati seguenti:

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

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

Passo 2: Importa il certificato nel tuo keystore

Formato PKCS#7. Poiché un file .p7b contiene già la catena completa, un singolo comando importa tutto in una volta, nel tuo alias esistente della 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 già contiene la tua chiave privata (l’alias del passaggio CSR). Quando vedi il messaggio Certificate reply was installed in keystore, l’importazione è andata a buon fine. 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ò conferma che il certificato firmato è ora collegato alla tua chiave privata.

Formato PEM. Importa i certificati separatamente, seguendo l’ordine della catena: prima il root, poi eventuali intermedi, e infine il certificato del tuo dominio. Importare prima la catena permette a keytool di costruire un percorso di attendibilità completo prima di collegare 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 attendibile, seguendo l’ordine in cui si firmano a vicenda (dal root verso il certificato del tuo dominio). Ad esempio, un certificato Sectigo Sectigo PositiveSSL viene fornito con più di un 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 utilizzato durante la generazione del 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 risposta al certificato e associa il certificato firmato alla chiave. Questo è il passaggio che rende funzionante HTTPS.

Errore critico da evitare: non importare il certificato firmato con un alias completamente nuovo. Se l’alias non ha una chiave privata esistente, keytool memorizza il certificato come voce attendibile 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.

Passo 3: Configura il connettore HTTPS in server.xml

Con il certificato nel tuo keystore, indirizza il connettore HTTPS di Tomcat verso di esso. Il connettore è definito in server.xml, situato nella cartella conf della tua installazione Tomcat (per 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 prevede un elemento SSLHostConfig annidato, che a sua volta contiene un elemento Certificate che fa riferimento al tuo keystore. Aggiungi o aggiorna il connettore sicuro in modo che assomigli a questo:

<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 ne contiene più di una.

Nota: la porta 443 è la porta HTTPS standard usata sopra; gli esempi predefiniti di Tomcat usano invece la porta 8443, quindi utilizza quella richiesta dal tuo ambiente. Se questa è la tua prima configurazione HTTPS, il connettore sicuro potrebbe essere commentato in server.xml. Rimuovi i marcatori di commento circostanti in modo che il connettore sia attivo, e assicurati che nessun altro connettore sia già associato alla stessa porta.

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

Passo 4: Salva server.xml e riavvia Tomcat

Salva server.xml, quindi 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 gestore dei servizi (per esempio systemctl restart tomcat su Linux, oppure il pannello Servizi su Windows). Congratulazioni, il tuo certificato SSL è ora installato sul tuo server Tomcat.

Verifica la tua installazione SSL su Tomcat

Dopo aver installato il certificato, piccoli errori possono insinuarsi senza essere notati e influire sul modo in cui i browser trattano il tuo sito. Prendi l’abitudine di verificare l’installazione. Esegui il nostro SSL Checker per una scansione immediata che rivela problemi come un certificato intermedio mancante o una catena non attendibile.

Domande frequenti