HTTPS e certificati

Quando un’app su un dispositivo connesso espone un’interfaccia web, l’Appliance la rende raggiungibile attraverso il suo tunnel integrato. Scegli come i browser raggiungono l’Appliance — ci sono tre modalità, dalla configurazione zero fino alla firma completamente aziendale. Scegline una e segui i suoi passaggi.

Non è la stessa cosa di Dietro un Proxy Aziendale. Quella pagina riguarda l’Appliance che si fida della tua CA aziendale per il traffico in uscita (Appliance → cloud, attraverso un proxy che intercetta il TLS). Questa pagina è la direzione opposta — il traffico in entrata dai browser sulla tua rete che raggiungono l’Appliance. Le due cose sono indipendenti.

Modalità 1 — HTTP semplice (predefinito)

Cosa ottieni. Tutto su HTTP semplice all’indirizzo dell’Appliance:

Ogni UI di app è pubblicata sulla propria porta assegnata automaticamente; la UI di IronFlock mostra il link esatto per ciascuna. Le UI delle app restano dietro il login dell’Appliance — aprirne una reindirizza al login a meno che tu non abbia effettuato l’accesso e sia autorizzato per quel dispositivo (una porta può essere contrassegnata come pubblica per singola app dove vuoi che sia aperta).

Cosa devi fare. Nulla. Questa è la modalità predefinita — basta usare l’IP o l’hostname dell’Appliance sulla tua rete locale. Nessun DNS, nessun certificato, nessun coinvolgimento dell’IT aziendale.

Quando usarla. Un’Appliance su una rete fidata e segmentata — un quadro di comando su una VLAN di macchina/OT — dove l’HTTP semplice è la norma e l’accesso è controllato dalla segmentazione della rete e dalla sicurezza fisica.

Modalità 2 — HTTPS con una CA autogenerata

Cosa ottieni. L’Appliance attiva il suo ingress HTTPS integrato e serve tutto su HTTPS sotto il tuo dominio — usando un certificato che genera da sé. Non c’è alcun reverse proxy da eseguire né URL da ricablare; l’installer collega tutto.

Cosa devi fare.

1. Scegli un dominio che risolva sull’Appliance per ogni browser e dispositivo che lo utilizzerà, e imposta sia APPLIANCE_HOST sia APPLIANCE_DOMAIN su di esso. Poiché l’Appliance emette il certificato da sé, funziona qualsiasi nome — l’unico requisito è che risolva. Per qualsiasi cosa oltre un test rapido, usa un dominio interno che controlli (ad esempio appliance.corp.example.com) con un record wildcard nel tuo DNS: una rete dell’Appliance isolata o con DNS limitato di solito non riesce a raggiungere il servizio pubblico nip.io su cui si basa il nome predefinito <host-ip>.nip.io. (Quel valore predefinito funziona dove la rete può raggiungere internet — ecco perché funziona su una macchina di sviluppo.)

2. Aggiungi DNS wildcard per il dominio, con entrambi i record che puntano all’IP host dell’Appliance:

   • *.<APPLIANCE_DOMAIN> — copre le UI delle app e ogni sottodominio di servizio.
   • <APPLIANCE_DOMAIN> (apex) — la UI principale per nome.

   (Un servizio DNS wildcard come nip.io risolve già questi automaticamente, quindi non ci sono record da aggiungere — ma dipende dalla raggiungibilità di quel servizio esterno.)

3. Installa con --tls:

   curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
     | sudo bash -s -- <your-instance-key> --interactive --tls

   --interactive richiede APPLIANCE_HOST / APPLIANCE_DOMAIN (oppure imposta IRONFLOCK_APPLIANCE_HOST / IRONFLOCK_APPLIANCE_DOMAIN per un’installazione automatica). L’Appliance genera una CA locale in /opt/ironflock/certs/ca/rootCA.crt e un certificato wildcard firmato da essa.

4. Distribuisci la root CA alle macchine client. Distribuisci rootCA.crt tramite il tuo MDM, oppure aggiungila allo store di trust del sistema operativo/browser di ogni macchina. Finché una macchina non si fida di essa, il suo browser mostra un avviso.

5. Rinnova entro un anno. Il certificato del server è limitato a circa 1 anno — i browser rifiutano quelli con durata maggiore. Per rinnovare, elimina tls.crt/tls.key nella directory dei certificati e riesegui l’installer; rifirma un nuovo certificato con la stessa CA, così la fiducia che hai distribuito continua a funzionare.

I dispositivi restano sul percorso con IP semplice. Solo il lato browser passa a HTTPS. I dispositivi connessi continuano a raggiungere l’Appliance tramite il suo IP, quindi non devi installare la CA su ogni dispositivo.

Quando usarla. Vuoi HTTPS su una rete condivisa ma non hai (o non vuoi attendere) un certificato dall’IT aziendale, e puoi distribuire una root CA alle macchine che apriranno la UI.

Modalità 3 — HTTPS con il tuo certificato aziendale

Cosa ottieni. Lo stesso HTTPS completo dell’Appliance della Modalità 2 — ma il certificato proviene dalla CA della tua organizzazione, la cui root è già fidata su ogni macchina gestita. Nessun avviso del browser, nulla da distribuire. Anche i dispositivi passano al dominio.

Cosa devi fare.

1. Scegli un dominio interno che controlli e imposta APPLIANCE_HOST e APPLIANCE_DOMAIN su di esso (ad esempio appliance.corp.example.com). Qui deve essere il tuo dominio — una CA emette certificati solo per i domini che possiedi, quindi un nome nip.io non funziona in questa modalità.
2. Aggiungi DNS wildcard — *.<APPLIANCE_DOMAIN> e l’apex, puntando all’IP host dell’Appliance — come nella Modalità 2, passo 2.
3. Ottieni un certificato wildcard per *.<APPLIANCE_DOMAIN> dalla tua CA interna, come due file PEM: tls.crt (idealmente full-chain) e una tls.key non cifrata.
4. Installa con il tuo certificato:

   curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
     | sudo bash -s -- <your-instance-key> --interactive \
         --tls-cert /path/to/wildcard.crt \
         --tls-key  /path/to/wildcard.key

   --tls-cert implica --tls. Variabili d’ambiente equivalenti: IRONFLOCK_TLS_CERT / IRONFLOCK_TLS_KEY.
5. Ruota secondo la pianificazione della tua CA. Copia i nuovi file PEM nella directory dei certificati e riavvia:

   sudo cp wildcard.crt /opt/ironflock/certs/tls.crt
   sudo cp wildcard.key /opt/ironflock/certs/tls.key
   sudo chmod 0600 /opt/ironflock/certs/tls.key
   sudo systemctl restart ironflock.service

   L’Appliance ricarica automaticamente il certificato quando il file cambia; il riavvio serve solo ad applicarlo immediatamente. Rieseguire l’installer non sovrascrive mai un certificato esistente a meno che tu non passi --tls-cert.

Anche i dispositivi passano al dominio. Poiché il certificato è fidato in tutta la flotta, anche il traffico dei dispositivi — il collegamento del dispositivo, i download delle immagini dei container e gli aggiornamenti dell’agent del dispositivo — passa sul dominio tramite TLS, e il workaround insecure-registries non è più necessario. Questo vale per le immagini delle app costruite dopo il passaggio; le app installate prima conservano l’indirizzo del registry contro cui sono state costruite, che l’agent 0.21.3 e successivi risolvono da sé — vedi il requisito 4 più sotto.

Cosa serve ai dispositivi collegati in questa modalità

Ogni dispositivo edge che si collega all’appliance deve:

1. Risolvere il dominio. <APPLIANCE_DOMAIN> e i suoi sottodomini (il record wildcard) devono risolvere all’IP dell’appliance dalla rete del dispositivo — gli stessi record DNS che servono i browser.
2. Raggiungere l’appliance sulla porta 443 — l’unica porta che serve ai dispositivi per la connessione alla piattaforma, per gli aggiornamenti dell’agent del dispositivo (serviti da https://registry.<APPLIANCE_DOMAIN>/dl — la porta 15002 non è necessaria in questa modalità) e per le immagini delle app costruite dopo il passaggio (le app installate prima rientrano nel requisito 4). È questo a rendere la modalità 3 la scelta giusta per i dispositivi su reti chiuse: la 443 in uscita è consentita quasi ovunque, e la connessione funziona anche attraverso un proxy HTTP aziendale (fornisci il proxy all’agent come descritto in Dietro un Proxy Aziendale → Dispositivi Edge). In modalità semplice, al contrario, i dispositivi hanno bisogno di accesso diretto a diverse porte di servizio dell’appliance che i firewall e i proxy aziendali bloccano di frequente — vedi Connettività dei dispositivi.
3. Fidarsi della tua CA radice aziendale. L’agent e Docker verificano il certificato dell’appliance contro l’archivio di attendibilità del sistema operativo del dispositivo:
   • Macchine gestite (Windows aggiunto al dominio, Linux gestito da MDM) di solito si fidano già della tua radice aziendale — non c’è nulla da fare.
   • Windows non gestito: installa la CA radice nell’archivio del computer da un prompt con privilegi elevati — certutil -addstore -f Root corporate-root-ca.crt — poi riavvia Docker Desktop (all’avvio importa le radici attendibili dall’archivio di Windows) e il servizio dell’agent (Restart-Service reagent).
   • Linux: sudo cp corporate-root-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates, poi riavvia Docker (sudo systemctl restart docker) e l’agent.
   • I container delle app ereditano automaticamente questa fiducia (agente 0.21.3 e successivi). Un container porta con sé solo il bundle di CA della propria immagine di base, e nessuna immagine di base contiene una radice interna: un’app che si collega all’appliance via TLS non poteva quindi verificarla. L’agente ora monta l’archivio attendibilità del dispositivo in sola lettura in ogni container di app, in /etc/ironflock/certs/ca-bundle.crt, e vi indirizza i runtime più comuni (SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS). Non c’è nulla da configurare, ma il dispositivo stesso deve fidarsi della radice, perché è proprio questa fiducia che l’agente trasmette. Se un’app imposta il proprio SSL_CERT_FILE, questo viene mantenuto.
4. Aggiornare l’agent del dispositivo a 0.21.3 o successivo — oppure ripubblicare le app installate prima del passaggio. Il file compose salvato di un’app porta con sé riferimenti immagine completamente qualificati — <APPLIANCE_IP>:15001/apps/… — fissati quando l’app è stata costruita. Quei riferimenti sono dati: spostare l’appliance su un dominio non riscrive nessun file compose. L’agent 0.21.3 e successivi risolvono un riferimento del genere sul registry per cui è configurato il dispositivo stesso, quindi un’app installata prima del passaggio continua a funzionare sul dominio senza alcun intervento — il primo avvio dopo l’aggiornamento scarica ogni immagine una volta con il nuovo nome. Un agent più vecchio usa il riferimento così com’è e continua a contattare il vecchio IP e la vecchia porta: il suo dispositivo ha ancora bisogno che la porta del registry (15001) sia raggiungibile sulla rete locale, e la sola porta 443 non gli basta, finché l’app non viene ricostruita e ripubblicata contro registry.<APPLIANCE_DOMAIN>. L’appliance gestisce automaticamente il proprio lato: finché il suo agent è precedente a 0.21.3 ed esiste un riferimento di questo tipo, mantiene il registry raggiungibile sulla LAN ed elenca i file compose interessati nell’output dell’installer. Una volta aggiornato l’agent — o ripubblicate quelle app — il successivo sudo ironflock-update non trova più nulla da attendere e sposta il registry fuori dalla LAN da sé.

Quando usarla. Il percorso on-prem aziendale standard: la tua organizzazione gestisce già una CA interna, quindi un certificato wildcard viene emesso una volta e fidato ovunque senza alcuna configurazione per singola macchina.

Risoluzione dei Problemi

Un link a una UI di app non si apre / connessione rifiutata. In modalità semplice le UI delle app sono a http://<host>:<port> — assicurati di usare il link esatto mostrato nella UI di IronFlock (la porta è assegnata per singola app) e che nulla sulla rete blocchi quella porta.

Il browser avverte che il certificato non è fidato (dopo --tls). Il client non si fida ancora della CA del certificato. Nella Modalità 2, distribuisci al client la CA generata dall’Appliance (/opt/ironflock/certs/ca/rootCA.crt). Nella Modalità 3, assicurati che il client si fidi della root della tua CA interna.

Certificato scaduto (autogenerato). Un certificato del server autogenerato è valido per circa un anno (i browser rifiutano quelli con durata maggiore). Rinnovalo: elimina tls.crt/tls.key nella directory dei certificati e riesegui l’installer per rifirmare con la stessa CA, ancora fidata — oppure passa a un --tls-cert dalla tua CA.

Mancata corrispondenza del nome del certificato. Il certificato non è un wildcard per il dominio in uso. Deve coprire *.<APPLIANCE_DOMAIN>, e il dominio dell’URL deve corrispondere a APPLIANCE_DOMAIN.

Un sottodominio non risolve (dopo --tls). Manca il DNS wildcard. Aggiungi un record A *.<APPLIANCE_DOMAIN> che punta all’host dell’Appliance — copre le UI delle app e ogni sottodominio di servizio.

Un’app non parte o non riesce a scaricare la sua immagine dopo il passaggio alla modalità 3 — “connection refused” sulla porta 15001. Il file compose dell’app fa ancora riferimento al registry tramite l’indirizzo IP dell’appliance, perché è contro quello che è stata costruita, e l’agent del dispositivo è precedente a 0.21.3 — da quella versione in poi l’agent risolve da sé un riferimento del genere sul proprio registry. Aggiorna l’agent del dispositivo, oppure ricostruisci e ripubblica l’app in modo che la sua immagine si risolva via registry.<APPLIANCE_DOMAIN>. Fino ad allora il registry deve restare raggiungibile sulla rete locale, cosa di cui l’appliance si occupa da sé — un semplice sudo ironflock-update ripristina il binding sulla LAN e nomina i file compose che conservano ancora un riferimento vecchio.

Un’app è in esecuzione ma non si collega mai e il suo log ripete lo stesso tentativo di connessione ogni pochi secondi. Il container dell’app non riesce a verificare il certificato dell’appliance: l’handshake TLS viene interrotto subito dopo il certificato del server e l’SDK riprova all’infinito, mentre il dispositivo resta online perché l’agente usa l’archivio attendibilità del sistema operativo e il container no. Aggiornare l’agente del dispositivo a 0.21.3 o successivo, che trasmette l’archivio attendibilità del dispositivo ai container delle app, e verificare che il dispositivo si fidi della radice aziendale (requisito 3 sopra). docker logs <container> sul dispositivo mostra l’errore di verifica del certificato. Con un agente più vecchio la soluzione è per singola app: aggiungere la CA radice all’immagine, oppure montarla e impostare SSL_CERT_FILE nel file compose dell’app.

Un dispositivo non si collega dopo il passaggio alla modalità 3. Ripercorri i quattro requisiti dei dispositivi qui sopra: il dominio deve risolvere dalla rete del dispositivo, la porta 443 sull’appliance deve essere raggiungibile (direttamente o tramite il proxy del dispositivo), il dispositivo deve fidarsi della tua CA radice aziendale, e le app installate prima del passaggio hanno bisogno dell’agent 0.21.3 o di una ripubblicazione prima di smettere di aver bisogno della porta del registry. Su Windows il log dell’agent in C:\ProgramData\IronFlock\Reagent\reagent.log (su Linux /var/log/reagent.log) mostra l’errore di connessione esatto — un fallimento DNS, un timeout o un errore di verifica del certificato puntano ciascuno a uno dei primi tre.