Come installare un certificato SSL su Unifi Cloud Key

Questo tutorial fornisce istruzioni passo passo su come installare un certificato SSL su un UniFi Cloud Key. Il Cloud Key esegue l’applicazione UniFi Network sopra un Java keystore, quindi l’installazione viene eseguita via SSH: si crea un bundle PKCS#12 dal certificato, dalla chiave privata e dalla catena CA, poi si importa nel keystore del Cloud Key con l’utility Java keytool e si riavvia il servizio UniFi.

Genera un codice CSR su UniFi Cloud Key

La Certificate Signing Request, o CSR, è un blocco di testo codificato che contiene i tuoi dati di contatto, come il dominio e l’organizzazione. Ogni richiedente deve generare un CSR e inviarlo alla Certificate Authority (CA) per la convalida prima che il certificato possa essere emesso. Per un Cloud Key, il common name nel CSR dovrebbe essere il nome host usato per raggiungere il controller, ad esempio unifi.iltuosito.com.

Hai due opzioni:

• Usa il nostro CSR Generator per creare automaticamente il CSR.
• Segui il nostro tutorial passo passo su come generare un CSR su UniFi Cloud Key.

Puoi aprire il file CSR con qualsiasi editor di testo, come Notepad, e incollarlo durante il processo di ordine del certificato con il tuo fornitore SSL. Conserva la chiave privata corrispondente al sicuro: ne avrai di nuovo bisogno al Passo 3 per creare il bundle PKCS#12. Una volta che la CA convalida la tua richiesta e invia via email i file SSL, prosegui con l’installazione descritta di seguito.

Installa un certificato SSL su UniFi Cloud Key

Il Cloud Key serve HTTPS da un Java keystore situato in /usr/lib/unifi/data/keystore. Per impostazione predefinita, questo keystore contiene un certificato autofirmato con l’alias unifi, protetto dalla password aircontrolenterprise. Per installare il proprio certificato si sostituisce questa voce: si raggruppano i file in un archivio PKCS#12, si importa nello stesso alias, quindi si riavvia il servizio UniFi. Lavorerai via SSH, quindi collegati prima al Cloud Key (l’utente SSH predefinito è root su Gen1, oppure l’account admin impostato durante l’adozione su Gen2).

Passo 1: Prepara i file SSL

Controlla la tua casella di posta e scarica l’archivio ZIP contenente il certificato. Estrailo. In base al tuo fornitore SSL, dovresti avere alcuni o tutti questi file:

• Il certificato SSL primario (il certificato del server).
• Il certificato SSL intermedio.
• Il certificato SSL root.
• Il CA bundle, un unico file che contiene già i certificati root e intermedio.

Ti serve anche la chiave privata generata insieme al CSR. Se hai usato il nostro CSR Generator, la chiave era disponibile per il download in quel momento.

Passo 2: Copia i file SSL sul Cloud Key

Carica i tuoi file sul Cloud Key tramite SCP o SFTP e posizionali in /etc/ssl/private/. Usa questi nomi in modo che corrispondano ai comandi dei passi successivi:

• Certificato primario come /etc/ssl/private/cloudkey.crt
• Chiave privata come /etc/ssl/private/cloudkey.key
• CA bundle (root e intermedio) come /etc/ssl/private/yourcaname.crt

Nota: ogni file PEM deve terminare con un a capo dopo la riga finale. La riga finale del certificato è esattamente cinque trattini, le parole END CERTIFICATE, poi cinque trattini (—–END CERTIFICATE—–); assicurati che ci sia un a capo dopo di essa. Un a capo finale mancante è una causa frequente di errori di importazione.

Passo 3: Raggruppa il certificato in un file PKCS#12

Combina la chiave privata, il certificato primario e il CA bundle in un unico file PKCS#12. L’alias deve essere unifi, perché è l’alias che il keystore UniFi si aspetta. Sostituisci enteryourpassword con una password a tua scelta e ricordala: dovrai passare lo stesso valore a keytool nel Passo 4 come password di origine.

openssl pkcs12 -export -in /etc/ssl/private/cloudkey.crt -inkey /etc/ssl/private/cloudkey.key -out /etc/ssl/private/cloudkey.p12 -name unifi -CAfile /etc/ssl/private/yourcaname.crt -caname root -password pass:enteryourpassword

Questo scrive /etc/ssl/private/cloudkey.p12, contenente la chiave, il certificato e la catena, tutto sotto l’alias unifi.

Passo 4: Importa il file PKCS#12 nel keystore del Cloud Key

Importa il file PKCS#12 nel keystore esistente in /usr/lib/unifi/data/keystore. Il keystore di destinazione usa già la password aircontrolenterprise, quindi le password dello store e della chiave di destinazione devono rimanere aircontrolenterprise. La password di origine è quella impostata sul file PKCS#12 al Passo 3.

keytool -importkeystore -deststorepass aircontrolenterprise -destkeypass aircontrolenterprise -destkeystore /usr/lib/unifi/data/keystore -srckeystore /etc/ssl/private/cloudkey.p12 -srcstoretype PKCS12 -srcstorepass enteryourpassword -alias unifi

Se keytool segnala che l’alias unifi esiste già, si riferisce alla voce predefinita autofirmata. Confirma la sovrascrittura quando richiesto, oppure elimina prima la vecchia voce con il comando seguente e poi esegui nuovamente l’importazione:

keytool -delete -alias unifi -keystore /usr/lib/unifi/data/keystore -storepass aircontrolenterprise

Importante: non modificare la password del keystore con un valore personalizzato. Il servizio UniFi è programmato per aprire il keystore con aircontrolenterprise; se la modifichi, il controller non potrà leggere il certificato e HTTPS non funzionerà.

Passo 5: Imposta i permessi e rimuovi i file temporanei

Restringi la proprietà e i permessi sui file in /etc/ssl/private/ in modo che la chiave privata non sia leggibile da tutti, quindi elimina i file intermedi che non ti servono più. Esegui questi comandi uno alla volta:

chown root:ssl-cert /etc/ssl/private/*
chmod 640 /etc/ssl/private/*
rm /etc/ssl/private/cloudkey.p12

Il certificato ora risiede all’interno del keystore, quindi il file PKCS#12 non è più necessario. Se hai caricato anche il CSR o il file CA solo per questo processo, puoi rimuoverli anch’essi:

rm /etc/ssl/private/cloudkey.csr
rm /etc/ssl/private/yourcaname.crt

Suggerimento: prima di riavviare, puoi eseguire un backup del keystore in modo da poter ripristinare la configurazione se necessario. Dall’interno di /usr/lib/unifi/data/, archivialo con tar -cvf keystore-backup.tar keystore.

Passo 6: Fai corrispondere il nome host del controller al tuo certificato

Affinché i browser si fidino del certificato senza un avviso di mancata corrispondenza del nome, imposta il nome host o l’IP del controller sul nome presente nel certificato. Nell’applicazione UniFi Network, vai su Settings > System (versioni precedenti: Settings > Controller) e imposta Controller Hostname/IP sul common name presente nel certificato, ad esempio unifi.iltuosito.com. Assicurati che quel nome host risolva al Cloud Key nel tuo DNS.

Passo 7: Riavvia il servizio UniFi

Il nuovo certificato viene letto solo quando il servizio UniFi si avvia, quindi riavvialo per caricare il tuo certificato:

service unifi restart

Sui firmware più recenti del Cloud Key che utilizzano systemd, il comando equivalente è:

systemctl restart unifi

Attendi un minuto affinché il servizio torni operativo, quindi ricarica il controller nel tuo browser. Congratulazioni, il tuo certificato SSL è ora installato sul tuo UniFi Cloud Key.

Verifica l’installazione SSL

Dopo aver installato il certificato, controlla la tua configurazione per errori o vulnerabilità come un certificato intermedio mancante o una catena non attendibile. Usa il nostro SSL Checker per una scansione e un report istantanei. Poiché il controller UniFi generalmente ascolta sulla porta 8443, indirizza il checker verso il tuo indirizzo completo, ad esempio unifi.iltuosito.com:8443. Puoi anche confermare il risultato dalla riga di comando:

echo | openssl s_client -connect unifi.yoursite.com:8443 -servername unifi.yoursite.com 2>/dev/null | openssl x509 -noout -issuer -dates

Questo stampa l’emittente del certificato e le date di validità, così puoi confermare che il Cloud Key serva il tuo certificato e non quello autofirmato precedente.

Domande frequenti