Riferimento della configurazione

Frontdoor legge la configurazione dalle variabili d'ambiente, di solito tramite un file .env. Il progetto include due esempi: .env.example.docker per Docker e .env.example.node per Node.js.

Con Docker, docker-compose.yml imposta da sé NODE_ENV, PORT, DATABASE_PATH e le cartelle sotto /data; questi valori non si possono cambiare dal .env.

Variabili d'ambiente

Server e archiviazione

Variabile	Descrizione	Predefinito
NODE_ENV	production disattiva il Login Dev e attiva i cookie sicuri	- (production in Docker)
PORT	Porta del server Express	3001
DATABASE_PATH	Percorso del file SQLite	./frontdoor.db
AVATAR_CACHE_DIR	Cache su disco per gli avatar degli utenti e i relativi metadati	./data/avatar-cache
APP_ICON_CACHE_DIR	Cache su disco per le icone delle app caricate e gli SVG incollati	./data/app-icon-cache
BRANDING_ASSET_DIR	Archiviazione su disco per il logo aziendale facoltativo	./data/branding
PLUGIN_ASSET_DIR	Archiviazione su disco per i pacchetti dei plugin (sistema di plugin attualmente bloccato)	./data/plugins
BACKUP_MAX_UPLOAD_MB	File di backup più grande accettato da Verifica backup e dal ripristino. I file caricati vengono scritti in streaming su un file temporaneo, non tenuti in memoria. Un reverse proxy davanti a Frontdoor richiede un limite corrispondente sulla dimensione delle richieste	1024
AVATAR_CACHE_TTL_DAYS	Intervallo di aggiornamento degli avatar Microsoft 365 / Gravatar in cache	14
AVATAR_CACHE_MISS_TTL_DAYS	Intervallo prima di un nuovo tentativo quando non è stato trovato alcun avatar	30
TIMEZONE (o TZ)	Fuso orario del server usato per data e ora dei log. Il valore predefinito per l'interfaccia si imposta in Personalizza	UTC
COMMIT_SHA	Commit registrato nei backup (argomento di build Docker)	-

Dominio e origini

Variabile	Descrizione	Predefinito
BASE_DOMAIN	Dominio di base, senza protocollo	frontdoor.local
FRONTEND_URL	URL del frontend con il protocollo. È considerata attendibile anche come origine per le richieste che modificano dati	https://frontdoor.local
CORS_ALLOWED_ORIGINS	Elenco, separato da virgole, delle origini autorizzate a chiamare Frontdoor con credentials: 'include', per le pagine con cookie condiviso o con controllo della sessione. Lascialo vuoto per disattivare CORS	-

Accesso e sessioni

Variabile	Descrizione	Predefinito
DEV_LOGIN	Attiva il Login Dev locale senza SSO Microsoft (ignorato in produzione)	false
AZURE_CLIENT_ID	ID applicazione (client) della registrazione di app in Entra	-
AZURE_CLIENT_SECRET	Client secret della registrazione di app in Entra	-
AZURE_TENANT_ID	ID directory (tenant)	-
AZURE_REDIRECT_URI	URI di reindirizzamento per il callback SSO	https://frontdoor.local/api/auth/microsoft/callback
JWT_SECRET	Secret di firma dei JWT	-
JWT_EXPIRES_IN	Durata del token JWT	7d
JWT_ISSUER	Emittente dei token di sessione e SSO. Le app satellite che verificano i token devono usare lo stesso valore	frontdoor
IMPERSONATION_TIMEOUT_MINUTES	Minuti in cui un amministratore può agire come un utente prima che l'impersonation termini (limitati tra 5 e 240)	30
ADMIN_EMAILS	Email degli owner, separate da virgole, promossi in automatico	-
ADMIN_API_KEY	Chiave API per gli endpoint bulk	-

Gruppi Microsoft Entra e notifiche

Variabile	Descrizione	Predefinito
ENTRA_GROUP_SYNC	Rileva le appartenenze ai gruppi Entra all'accesso e attiva i flussi di importazione e sincronizzazione per gli amministratori	false (true in docker-compose.yml)
ENTRA_TENANT_REFRESH_MINUTES	Minuti minimi tra due aggiornamenti, avviati dagli accessi, del catalogo dei gruppi Entra dell'intero tenant. Una sincronizzazione manuale lo aggiorna sempre; 0 lo aggiorna a ogni accesso	360
ENTRA_DELETED_GROUP_POLICY	Cosa succede ai membri di un gruppo Entra che Microsoft Entra segnala come eliminato: freeze mantiene il loro accesso finché un amministratore non decide; revoke lo rimuove al prossimo accesso o alla prossima sincronizzazione. In entrambi i casi il gruppo viene contrassegnato, se ne conserva un'istantanea e gli amministratori vengono avvisati	freeze
NOTIFICATION_RETENTION_DAYS	Giorni per cui una notifica per gli amministratori già risolta viene conservata prima che la pulizia giornaliera la rimuova	30

Limiti di frequenza

Tutti i limiti valgono per singolo indirizzo IP.

Variabile	Descrizione	Predefinito
AUTH_RATE_LIMIT_MAX / AUTH_RATE_LIMIT_WINDOW_MS	Endpoint di accesso Microsoft	5000 / 15 min
RBAC_RATE_LIMIT_MAX / RBAC_RATE_LIMIT_WINDOW_MS	Modifiche a gruppi e utenti	500 / 15 min
API_RATE_LIMIT_MAX / API_RATE_LIMIT_WINDOW_MS	Il resto dell'API	6000 / 15 min

Checklist per la produzione

Per un'installazione reale, imposta almeno:

• NODE_ENV=production (già impostato da docker-compose.yml; il Login Dev è sempre disattivato in produzione)
• BASE_DOMAIN e FRONTEND_URL
• AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID e AZURE_REDIRECT_URI
• un JWT_SECRET univoco di almeno 32 caratteri
• ENTRA_GROUP_SYNC se vuoi la sincronizzazione dei gruppi Entra
• CORS_ALLOWED_ORIGINS se una pagina statica o un'app satellite su un'altra origine deve chiamare Frontdoor con le credenziali

Consigliati:

• ADMIN_EMAILS
• ADMIN_API_KEY
• JWT_EXPIRES_IN
• un fuso orario predefinito del tenant in Personalizza, se vuoi qualcosa di diverso da UTC

Se un valore obbligatorio manca o non è valido, Frontdoor si ferma all'avvio con un messaggio chiaro nei log, invece di fallire più tardi con un errore di autenticazione.

Controllo della sessione da altre origini

CORS_ALLOWED_ORIGINS serve alle pagine che devono solo sapere se l'utente ha già una sessione Frontdoor attiva: per esempio una semplice pagina statica o una pagina di download su un dominio vicino.

Se ospiti una pagina su https://contoso.com, imposta:

CORS_ALLOWED_ORIGINS=https://contoso.com

La pagina può quindi chiedere a Frontdoor se la sessione del browser è autenticata:

<script>
  async function checkSession() {
    const response = await fetch('https://frontdoor.contoso.com/api/auth/me', {
      credentials: 'include',
    });

    if (response.ok) {
      const { user } = await response.json();
      console.log('Signed in as:', user.email || user.displayName);
      return;
    }

    window.location.href = 'https://frontdoor.contoso.com/login';
  }

  checkSession().catch(() => {
    window.location.href = 'https://frontdoor.contoso.com/login';
  });
</script>

credentials: 'include' dice al browser di inviare il cookie frontdoor_token con la richiesta. Frontdoor accetta la richiesta da un'altra origine solo se l'origine della pagina è elencata in CORS_ALLOWED_ORIGINS.

Log di avvio

All'avvio il server stampa un riepilogo della configurazione, con i valori sensibili oscurati:

Frontdoor startup configuration:
  NODE_ENV=production
  PORT=3001
  DATABASE_PATH=/data/frontdoor.db
  BRANDING_ASSET_DIR=/data/branding
  BASE_DOMAIN=contoso.com
  FRONTEND_URL=https://frontdoor.contoso.com
  CORS_ALLOWED_ORIGINS=[empty]
  TIMEZONE=UTC
  DEV_LOGIN=disabled
  AZURE_CLIENT_ID=[set]
  AZURE_CLIENT_SECRET=[set]
  AZURE_TENANT_ID=[set]
  AZURE_REDIRECT_URI=https://frontdoor.contoso.com/api/auth/microsoft/callback
  JWT_SECRET=[set]
  ADMIN_EMAILS=1 owner configured

Gli avvisi segnalano i valori predefiniti e le impostazioni valide ma deboli, per esempio:

• BASE_DOMAIN is not set, defaulting to frontdoor.local
• JWT_SECRET is shorter than 32 characters; use a longer random secret in production