Windows Server with IIS

Esegui il deployment di FoxIDs su Windows Server con Internet Information Services, IIS.

Questa e una descrizione di come eseguire un deployment predefinito e accedere per la prima volta.

Una installazione FoxIDs è autonoma, ha poche dipendenze esterne e può ottenere un uptime molto elevato con poco sforzo. FoxIDs viene aggiornato scaricando il file FoxIDs-x.x.x-win-x64.zip dalla nuova release e poi aggiornando i file nei due siti web, senza sovrascrivere appsettings.json. Le nuove release FoxIDs sono backward compatible; consulta le release notes prima di aggiornare.

Per accedere alle release FoxIDs, da cui puoi scaricare i file di deployment richiesti, e necessaria una licenza valida.

Prerequisiti:

Hai un Windows Server, oppure Windows 10 o 11, con Internet Information Services, IIS.
Hai conoscenze di base di Windows Server e IIS.

Questa guida descrive come installare FoxIDs su un singolo server, ma puoi suddividere l'installazione su server differenti.

Questo deployment include:

Due siti web, uno per FoxIDs e uno per FoxIDs Control, Admin Client e API.
I due siti web sono esposti su due domains o sub-domains differenti.
Un database NoSQL che contiene tutti i dati inclusi tenant, ambienti e utenti. Distribuisci MongoDB Community Edition oppure PostgreSQL.
Con "Log": "Stdout", FoxIDs scrive i log su stdout. IIS stdout file logging è disabilitato nei file web.config inclusi; abilitalo temporaneamente per il troubleshooting oppure usa OpenSearch in produzione.

Deployment

Il deployment viene eseguito nell'ordine descritto.

Install database

Scarica e installa MongoDB Community Edition oppure scarica e installa PostgreSQL.

MongoDB
Un deployment MongoDB self-managed viene installato per impostazione predefinita con access control disabilitato. Valuta di configurare l'autenticazione MongoDB in base alla tua installazione.
Endpoint predefinito, connection string, di MongoDB: mongodb://localhost:27017

Puoi installare MongoDB Compass, GUI, con MongoDB Community Edition oppure scaricare e installare separatamente l'applicazione di amministrazione MongoDB.

PostgreSQL
PostgreSQL viene distribuito per impostazione predefinita con l'utente postgres e una password che fornisci durante l'installazione.

Apri pgAdmin e crea un database per FoxIDs chiamato FoxIDs

Endpoint predefinito, connection string, di PostgreSQL: Host=localhost;Username=postgres;Password=xxxx;Database=FoxIDs

Add two websites

Abilita ASP.NET Core hosting e aggiungi i due siti web FoxIDs a IIS.

Aggiungi ASP.NET Core Module, ANCM, per IIS

Installa il .NET Core Hosting Bundle installer (direct download) per aggiungere ASP.NET Core Module, ANCM, per IIS, che e richiesto per eseguire applicazioni ASP.NET Core, anche se i siti web FoxIDs sono self-contained.
Riavvia IIS oppure il server

Aggiungi il sito web FoxIDs:

Nome sito FoxIDs
Physical path, ad esempio C:\inetpub\FoxIDs
Il binding del domain http per il tuo dominio, ad esempio http://id.my-domain.com
Cambia l'app service .NET CLR Version in No Managed Code

E aggiungi il sito web FoxIDs Control:

Nome sito FoxIDs.Control
Physical path, ad esempio C:\inetpub\FoxIDs.Control
Il binding del domain http per il tuo dominio, ad esempio http://control.my-domain.com
Cambia l'app service .NET CLR Version in No Managed Code

Facoltativamente aggiungi i due domains al file hosts del server C:\Windows\System32\drivers\etc\hosts per abilitare test locali sul server:
   127.0.0.1     id.my-domain.com
   127.0.0.1     control.my-domain.com

HTTP and HTTPS

FoxIDs supporta sia HTTP sia HTTPS, ma in produzione dovresti sempre usare HTTPS.

Puoi saltare questa sezione se vuoi eseguire FoxIDs in HTTP senza certificato.

Puoi usare i tuoi certificati oppure fare creare un certificato da Let's encrypt.

Use your own certificate(s)
Installa i tuoi certificati sul server e configura binding https per i due siti web.

Windows Server with IIS - add the FoxIDs website

Certificate created by Let's encrypt
Crea e aggiungi il certificato Let's encrypt ai due siti web con win-acme.

Scarica il file win-acme.v2.x.x.x64.pluggable.zip dall'ultima release win-acme.

Estrai e posiziona la cartella win-acme.v2.x.x.x.x64.pluggable in una posizione permanente, ad esempio sul disco C. Il componente viene poi registrato per essere eseguito in Windows Task Scheduler.
Avvia un Command Prompt elevato in modalita amministrativa
Vai alla cartella win-acme.v2.x.x.x.x64.pluggable
Esegui wacs.exe
Fai clic su N
Seleziona i siti web FoxIDs e FoxIDs.Control, probabilmente digitando: 2, 3
Fai clic su A
Scegli il sito FoxIDs come host principale
Accetta i termini, fai clic su N e poi su Y
Aggiungi la tua email

I due siti web ora hanno binding https con il certificato creato da Let's encrypt e il certificato verra aggiornato automaticamente ogni 3 mesi circa.

Xcopy deploy FoxIDs to websites

Scarica il file FoxIDs-x.x.x-win-x64.zip dalla release FoxIDs ed estrai il file ZIP. Il file zip contiene due cartelle, una per il sito FoxIDs e una per il sito FoxIDs Control.

Esegui Xcopy della cartella FoxIDs del file zip nel physical path del sito web, ad esempio C:\inetpub\FoxIDs
Ed esegui Xcopy della cartella FoxIDs.Control del file zip nel physical path del sito web, ad esempio C:\inetpub\FoxIDs.Control

Configura sia il sito FoxIDs sia il sito FoxIDs Control nei file appsettings.json, situati ad esempio in C:\inetpub\FoxIDs\appsettings.json e C:\inetpub\FoxIDs.Control\appsettings.json

Imposta il domain del sito FoxIDs in FoxIDsEndpoint, ad esempio http://id.my-domain.com oppure https://id.my-domain.com
Solo nel sito FoxIDs Control. Imposta il domain del sito FoxIDs Control in FoxIDsControlEndpoint, ad esempio http://control.my-domain.com oppure https://control.my-domain.com
Se il domain inizia con http://..., rimuovi il commento da "UseHttp": true,

Configura l'accesso al database, o a MongoDB

"Options": {
    "Log": "Stdout",
    "DataStorage": "MongoDb",
    "KeyStorage": "None",
    "Cache": "MongoDb",
    "DataCache": "None"
},
"MongoDb": {
    "ConnectionString": "mongodb://localhost:27017"
},

oppure a PostgreSql con la password del tuo utente postgres

"Options": {
    "Log": "Stdout",
    "DataStorage": "PostgreSql",
    "KeyStorage": "None",
    "Cache": "PostgreSql",
    "DataCache": "None"
},
"PostgreSql": {
  "ConnectionString": "Host=localhost;Username=postgres;Password=xxxxxxxx;Database=FoxIDs"
},

Facoltativamente configura l'invio di email con SMTP.

Patching and update strategy

L'aggiornamento di FoxIDs segue la stessa meccanica del deployment Xcopy, ma un po di struttura aggiuntiva mantiene basso il downtime e fornisce un percorso semplice di rollback.

Plan the window - Controlla le ultime release notes, FoxIDs e backward compatible, salvo diversa indicazione nelle release notes, e pianifica una breve finestra di manutenzione. Se i due siti sono dietro un load balancer, svuota il traffico da un nodo alla volta.
Stage the binaries - Scarica l'ultimo FoxIDs-x.x.x-win-x64.zip, estrailo in cartelle temporanee come C:\temp\FoxIDs.new e C:\temp\FoxIDs.Control.new, e copia i tuoi file appsettings*.json e web*.config esistenti.
Snapshot the current install - Arresta i due siti IIS, oppure i relativi App Pools. Esegui Xcopy oppure rinomina le cartelle live, ad esempio C:\inetpub\FoxIDs → C:\inetpub\FoxIDs.2025-11-11.bak. Fai lo stesso per il sito Control. Anche un backup compresso o uno snapshot VM vanno bene, ma copie rapide delle cartelle spesso sono sufficienti.
Swap in the update - Esegui Xcopy delle cartelle preparate nei percorsi live, C:\inetpub\FoxIDs e C:\inetpub\FoxIDs.Control, e ricontrolla che i permessi NTFS ereditati includano ancora le identita corrette degli App Pool. Riavvia App Pools o siti per riscaldare le applicazioni.
Verifica e monitora - Apri il sito Control, completa un round-trip di login ed esegui una rapida tenant o track lookup. Se hai abilitato IIS stdout file logging, osserva la cartella dei log C:\inetpub\logs\LogFiles\foxids per errori. Se usi OpenSearch, controlla log ed errori in OpenSearch.
Rollback if needed - Se qualcosa si comporta male, arresta i siti, rinomina le cartelle appena distribuite in .failed, ripristina le cartelle .bak ai nomi originali e riavvia IIS. Poiche lo schema del database e backward compatible, i binari precedenti riprenderanno subito a funzionare.

Ripeti il processo per ogni release; in configurazioni multi-server aggiorna un server alla volta per mantenere la disponibilita del servizio.

FoxIDs log files

Con "Log": "Stdout", FoxIDs scrive i log su stdout. I file web.config inclusi impostano stdoutLogEnabled="false" e stdoutLogFile="\\?\%home%\LogFiles\stdout".

Gli errori di startup di IIS e gli errori del processo applicativo FoxIDs vengono scritti anche nel Windows Application event log e possono essere visualizzati in Event Viewer.

Se ti servono file di log durante il troubleshooting di problemi di startup o runtime IIS, abilita temporaneamente stdoutLogEnabled e imposta stdoutLogFile su un path come C:\inetpub\logs\LogFiles\foxids\stdout nei file web.config di entrambi i siti web.

Crea la cartella \foxids\ in C:\inetpub\logs\LogFiles\ e concedi ai due IIS App Pools iis apppool\foxids e iis apppool\foxids.control accesso completo alla cartella \foxids\. Disabilita di nuovo IIS stdout file logging dopo il troubleshooting.

I log contengono errori, warning, eventi e trace.

OpenSearch

In base al carico valuta l'uso di OpenSearch in produzione invece dei file di log.

Scarica OpenSearch oppure scaricalo dalla download page.

Crea una cartella in una posizione permanente, ad esempio C:\opensearch sul disco C. OpenSearch viene poi installato per essere eseguito come Windows Service.
Sposta il file scaricato opensearch-x.x.x-windows-x64.zip nella cartella C:\temp, oppure un'altra cartella con nome corto, ed estrailo - i nomi dei file sono troppo lunghi per essere estratti nella cartella di download predefinita
Sposta i file estratti nella cartella C:\opensearch
Avvia un Command Prompt elevato in modalita amministrativa
Vai alla cartella C:\opensearch
Imposta una password amministratore, esegui set OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>
Avvia il servizio, esegui \.\opensearch-windows-install.bat
Avvia un altro Command Prompt
Testa OpenSearch, esegui la richiesta di test curl.exe -X GET https://localhost:9200 -u "admin:<custom-admin-password>" --insecure
Testa i plugin OpenSearch, esegui la richiesta di test curl.exe -X GET https://localhost:9200/_cat/plugins?v -u "admin:<custom-admin-password>" --insecure
Torna al Command Prompt di OpenSearch e arresta OpenSearch con ctrl+c e poi y
Le impostazioni si trovano in C:\opensearch\config\opensearch.yml; controllale.
Vai alla cartella C:\opensearch\bin nel Command Prompt di OpenSearch
Esegui opensearch-service.bat install per installare OpenSearch Windows Service
Esegui opensearch-service.bat manager per aprire le impostazioni di OpenSearch Windows Service
Imposta Startup type: su Automatic e fai clic su OK
Esegui opensearch-service.bat start per avviare OpenSearch Windows Service

OpenSearch viene avviato per impostazione predefinita con un certificato self-signed. Puoi configurare un domain e un certificato, ma in questa guida il certificato self-signed viene mantenuto e FoxIDs viene configurato per accettarlo.

Configura OpenSearch sia nel sito FoxIDs sia nel sito FoxIDs Control nei file appsettings.json, situati ad esempio in C:\inetpub\FoxIDs\appsettings.json e C:\inetpub\FoxIDs.Control\appsettings.json

"Options": {
    "Log": "OpenSearchAndStdoutErrors",
    //DB configuration...
},
"OpenSearch": {
    "Nodes": [ "https://admin:xxxxxxxx@localhost:9200" ],
    "LogLifetime": "Max180Days", 
    "AllowInsecureCertificates": true //Accept self-signed certificate
},

Secure connection strings

In produzione si raccomanda di usare connection strings con password per MongoDB, PostgreSQL e OpenSearch.

Non memorizzare le password in appsettings.json. Mantieni i valori non segreti in appsettings.json e configura i segreti come environment variables in IIS sia per il sito FoxIDs sia per il sito FoxIDs Control. Le environment variables sovrascrivono i valori in appsettings.json.

Configura queste environment variables in IIS:

MongoDb__ConnectionString
PostgreSql__ConnectionString
OpenSearch__Nodes__0, primo nodo OpenSearch incluso di credenziali

Imposta solo le variabili che usi.

Valori di esempio:

MongoDb__ConnectionString=mongodb://foxids:<password>@localhost:27017
PostgreSql__ConnectionString=Host=localhost;Username=postgres;Password=<password>;Database=FoxIDs
OpenSearch__Nodes__0=https://admin:<password>@localhost:9200

I valori vengono salvati nella configurazione IIS, applicationHost.config, fuori dalla web root. Limita l'accesso ai file di configurazione IIS ai soli amministratori.

Per configurare le variabili in IIS:

Apri IIS Manager.
Seleziona il sito, FoxIDs oppure FoxIDs.Control.
Apri Configuration Editor.
Vai a system.webServer/aspNetCore.
Aggiungi i valori sotto environmentVariables.
Ripeti per il secondo sito e riavvia entrambi gli App Pools.

Apri nel browser il tuo sito FoxIDs Control, http://control.my-domain.com oppure https://control.my-domain.com. Dovrebbe reindirizzare al sito FoxIDs dove esegui il login con l'utente admin predefinito admin@foxids.com e password FirstAccess!, ti viene richiesto di cambiare la password al primo login.
Vieni quindi reindirizzato di nuovo al sito FoxIDs Control nel tenant master. Puoi aggiungere altri utenti admin nel tenant master.

Poi fai clic sul tenant main ed esegui di nuovo l'autenticazione con lo stesso utente admin predefinito admin@foxids.com e password FirstAccess!, anche qui ti viene richiesto di cambiare la password.

L'utente admin predefinito e la password sono gli stessi sia per il tenant master sia per il tenant main, ma sono due utenti differenti.

Ora hai effettuato l'accesso al tenant main e puoi iniziare a configurare le tue applications e i tuoi authentication methods.