Richiedere Certificati SSL in ServBay con ACME

ServBay supporta la richiesta automatica di certificati SSL/TLS per i tuoi siti di sviluppo locale tramite il protocollo ACME. ACME (Automated Certificate Management Environment) è uno standard che automatizza l’intero ciclo di vita dei certificati—richiesta, rinnovo e revoca. Attraverso il pannello ACME integrato di ServBay puoi configurare rapidamente certificati SSL attendibili per i siti locali, essenziale per simulare un ambiente di produzione e testare funzionalità legate ad HTTPS.

Di default ServBay sfrutta ZeroSSL per l’emissione, ma puoi scegliere anche Let's Encrypt, Google Trust Services o qualsiasi altra Certification Authority (CA) compatibile con ACME.

TIP

Usare certificati SSL attendibili è cruciale per mantenere un ambiente di sviluppo coerente con quello in produzione. ACME su ServBay rende questo processo incredibilmente semplice.

Glossario: Concetti Fondamentali

Prima di iniziare, ecco alcuni termini utili per comprendere meglio le funzionalità ACME di ServBay:

• Protocollo ACME: Uno standard aperto per automatizzare l’interazione tra CA (Certification Authority) e server, gestendo richiesta, rinnovo e revoca dei certificati.
• Verifica DNS-01 (tramite API DNS): ACME supporta diversi metodi di verifica della proprietà del dominio. ServBay utilizza DNS-01: la CA richiede di aggiungere un record TXT specifico nei DNS del dominio per dimostrare il controllo. Questo metodo offre vantaggi:
  • Non richiede che il sito locale sia accessibile pubblicamente.
  • Funziona anche se le porte 80/443 sono bloccate da firewall o ISP.
• External Account Binding (EAB): Alcune CA (come Google Trust Services o ZeroSSL) richiedono, durante la prima richiesta, l’associazione dell’account utente al client ACME (qui: acme.sh integrato in ServBay), tramite Key ID e HMAC Key.
• Certificato ECC vs RSA:
  • RSA: Algoritmo tradizionale, ottima compatibilità, ma chiavi più lunghe (2048 o 4096 bit) e maggior carico computazionale.
  • ECC (Elliptic Curve Cryptography): Algoritmo moderno, stessa sicurezza con chiavi molto più brevi (256 o 384 bit). Offre migliori prestazioni, handshake più rapido, minore uso di banda e migliori caratteristiche di forward secrecy. ServBay consiglia ECC di default.

Prerequisiti

La richiesta ACME tramite DNS API su ServBay non richiede che il sito sia accessibile da Internet. Prima della richiesta di certificato SSL tramite ACME, assicurati di:

1. Possedere un dominio: Deve essere già registrato e devi poter modificare i suoi record DNS.
2. Ottenere l’API Key del provider DNS: Sarà necessaria per l’aggiunta automatica/rimozione dei record TXT di verifica tramite API. Recupera le istruzioni per il tuo provider consultando la sezione Wiki DNS API (in inglese) di acme.sh: How to use DNS API.
3. Recuperare le informazioni EAB (per Google Trust Services o ZeroSSL): Se usi Google Trust Services, ottieni i dati EAB da Google Cloud seguendo la guida officiale (EN): Obtaining EAB credentials from Google Cloud. Con ZeroSSL potrebbe anche essere richiesta la verifica via email o l’API Key al primo utilizzo.

Richiedere un Certificato SSL con ACME su ServBay

Segui questi step per richiedere un certificato SSL ACME per il tuo sito di sviluppo locale in ServBay:

1. Apri il pannello di controllo ServBay
   Avvia ServBay e accedi al pannello tramite l’icona nella barra dei menu o nel Dock.

2. Vai alla gestione Certificati SSL
   Nel menu a sinistra, seleziona “Certificati SSL”.

3. Avvia una nuova richiesta
   Nella gestione certificati, in alto a destra clicca su + e scegli “Richiedi nuovo certificato”.

4. Configura le informazioni di base

   • Nome certificato: Assegna un nome identificativo (es: servbay-demo-ssl).
   • Utilizzo: Scegli TLS/SSL.
   • Metodo di richiesta: Seleziona ACME.

5. Scegli la Certification Authority (CA) Nel menu a tendina “Emittente”, scegli la CA desiderata (di default ZeroSSL). Puoi selezionare anche Let's Encrypt o Google Trust Services.

6. Seleziona il provider DNS API Nel menu corrispondente indica il provider DNS effettivo (esempio: Cloudflare). Attenzione: devi selezionare la piattaforma che gestisce i DNS del dominio, non necessariamente dove hai acquistato il dominio.

7. Seleziona algoritmo del certificato e lunghezza chiave

   • Algoritmo: Consigliato ECC per performance e sicurezza. Se devi supportare dispositivi molto vecchi scegli RSA.
   • Lunghezza chiave: ECC di default 384 bit è sufficiente. RSA comunemente 2048 o 4096 bit.

8. Inserisci i dati di verifica In base alla CA e provider DNS scelti, compila i campi richiesti:

   • Per ZeroSSL, di solito basta l’indirizzo email.
   • Per Cloudflare DNS API, serve la tua API Key o altra credenziale come da istruzioni acme.sh.

   WARNING

   Attenzione: incolla solo il valore della chiave API o della secret; non aggiungere prefissi come export usati nella shell.

9. Definisci il dominio Nel campo “Dominio”, specifica il dominio per il certificato (es: servbay.demo o *.servbay.demo). Per wildcard (*.), il provider DNS deve supportare l’automazione dei record TXT per domini wildcard.

10. Invia la richiesta Dopo aver verificato tutti i dati, clicca su “Richiedi”. ServBay userà acme.sh e le API DNS per convalidare il dominio e inviare la richiesta.

La procedura potrebbe richiedere alcuni minuti, variando in base alla propagazione DNS e alla rapidità di risposta della CA. Lo stato dell’operazione è consultabile nei log o nell’elenco certificati. Al termine, il nuovo certificato apparirà nella lista “Certificati SSL”.

Interrompere una richiesta in corso

Quando ACME è in stato di richiesta, il bottone “Richiedi” diventa “Interrompi richiesta”. Se la procedura si blocca troppo a lungo (es. DNS lenti o errore nelle credenziali), puoi interrompere la richiesta, correggere i dati e ricominciare subito senza attendere timeout automatico.

Opzioni Avanzate: Attesa Propagazione DNS & Salto Auto-Controllo DNS

Di default, acme.sh attende che il record TXT di verifica sia propagato e ne verifica la presenza localmente prima di notificarlo alla CA. Tuttavia, in alcune reti (es. DNS spoofing locale, modalità fake-ip, o mismatch tra risoluzione locale e pubblica) il controllo locale può fallire o impiegare troppo tempo anche se il record è valido globalmente.

Per questi casi, ServBay offre due opzioni avanzate:

• Secondi di attesa: Imposta un tempo di attesa (default: 120s) per la propagazione DNS globale prima della convalida da parte della CA.
• Salta auto-controllo DNS: Se attivato, acme.sh salta il test locale sul TXT record e affida la verifica direttamente alla CA al termine dell’attesa. Utile in ambienti dove il DNS locale non riflette l’effettivo stato pubblico.

TIP

Di solito non serve modificare queste opzioni: lasciale di default, salvo incontrare problemi del tipo “TXT record valido ma verifica locale sempre fallita” (tipici in reti con DNS spoofing). In quel caso, prova ad abilitare “Salta auto-controllo DNS” e/o ad aumentare il tempo di attesa.

Usare il Certificato nelle Configurazioni Sito ServBay

Una volta ottenuto il certificato ACME, puoi associarlo facilmente ai siti configurati in ServBay:

1. Dal menu a sinistra apri “Siti”.
2. Seleziona il sito desiderato e clicca sull’icona modifica (matita).
3. Tra i dettagli della configurazione, cerca “Certificato SSL”.
4. Seleziona dal menu a tendina il certificato appena richiesto.
5. Assicurati che l’opzione “Abilita SSL” sia attiva.
6. Salva la configurazione. Ora il tuo sito sarà accessibile tramite HTTPS.

Rinnovo dei Certificati ACME

I certificati ACME (es. Let's Encrypt e ZeroSSL) hanno tipicamente durata di 90 giorni. Per garantire un HTTPS sempre funzionante, vanno rinnovati prima della scadenza.

ServBay gestisce in automatico la validità dei certificati richiesti tramite ACME, avviando la procedura di rinnovo con i dati API DNS precedentemente configurati quando il certificato è in scadenza.

Se lasci le API key DNS valide e il servizio DNS stabile, non serve l’intervento manuale per il rinnovo: ServBay si occuperà di tutto in background.

FAQ & Risoluzione dei Problemi

• Errore: fallimento verifica DNS durante la richiesta?
  • Ricontrolla che le credenziali API DNS siano corrette e con permessi per modificare TXT record.
  • Assicurati che il provider DNS selezionato corrisponda effettivamente a chi gestisce i DNS del dominio.
  • Attendi la completa propagazione globale dei record DNS (a volte servono diversi minuti).
  • Controlla che il dominio inserito sia corretto.
  • Se la verifica locale fallisce ma il record TXT è correttamente online (caso comune con DNS spoofing o modalità fake-ip), attiva “Salta auto-controllo DNS” e aumenta l’attesa (vedi “Opzioni Avanzate” sopra).
• Errore legato a EAB?
  • Se usi Google Trust Services o ZeroSSL per la prima volta, verifica di aver inserito correttamente i dati EAB.
  • Se funzionava in passato ma ora fallisce, potrebbe essere necessario aggiornare le credenziali EAB.
• Messaggio: superato limite di richieste (Rate Limit)?
  • Le CA limitano il numero di richieste per dominio/IP in un certo periodo. Se hai provato troppe volte in poco tempo, attendi alcune ore (o giorni) e riprova.
• Certificato OK, ma il sito appare comunque “non sicuro” nel browser?
  • Assicurati di aver applicato il certificato al sito tramite la configurazione e di aver abilitato SSL.
  • Pulisci la cache del browser o prova in modalità in incognito.
  • Verifica che il tuo file Hosts o altre configurazioni di rete reindirizzino correttamente verso ServBay.
• Quando si avvia in automatico il rinnovo? ServBay comincia i tentativi di rinnovo automatico alcuni giorni prima della scadenza (es. 30 giorni). Basta che l’app sia in esecuzione e la connessione a Internet attiva: il rinnovo avviene in background.

Conclusioni

ServBay offre un sistema ACME potente e intuitivo per richiedere e gestire certificati SSL/TLS affidabili tramite API DNS anche in ambiente locale. Questo semplifica la configurazione, migliora la sicurezza e permette un ambiente di sviluppo fedele al contesto di produzione, facilitando test e debugging HTTPS.

Speriamo che questa guida ti aiuti a sfruttare al meglio l’ACME in ServBay, rendendo la tua esperienza di sviluppo locale più sicura ed efficiente.