node-user-auth

In sintesi

Auth backend trasversale del namespace ditta: ogni richiesta che arriva sugli altri ingress passa prima da qui via nginx auth_request, e solo se la risposta è 200 la richiesta originale viene inoltrata al microservizio applicativo. Il servizio non memorizza password — l'identità arriva da un Identity Provider esterno (OAuth2/OIDC o claim propagati da nginx) e qui viene materializzata in sessione, ruolo Postgres, claim JWT e cookie. Espone quattro strategie di autenticazione (nginx, apiKey, oauth, jwt) che coprono traffico utente da browser, comunicazione M2M fra microservizi e accessi di sviluppo o test.

Funzionalità principali

• Multi-strategia auth sullo stesso processo: subrequest nginx per il traffico web di default, apiKey per ambienti dev/test, oauth con token introspection per M2M, jwt self-contained per casi che richiedono token firmato verificabile offline
• Endpoint /nginx/auth dedicato a auth_request: valida cookie/JWT, esegue refresh inline trasparente e propaga gli header X-Auth-User, X-Auth-User-ID, X-Auth-Session-ID al backend protetto
• Sessioni server-side su Redis con TTL standard ed esteso ("remember me"), limite di sessioni concorrenti, cleanup periodico e revoca puntuale o massiva
• JWT asimmetrici RS256/EdDSA firmati con chiave privata custodita dal servizio; chiave pubblica esposta via JWKS per la verifica da parte degli altri microservizi
• Token rotation dei refresh token con detection del riuso (reuse → revoca dell'intera famiglia)
• OAuth2/OIDC completo: Authorization Code + PKCE, Client Credentials, Refresh, Token Exchange (RFC 8693), Device Authorization Grant, introspection endpoint per i consumer M2M
• MFA TOTP opzionale con backup codes, integrato nel flusso di login standard
• Rate limiting e brute-force protection specifici per endpoint sensibili (/auth/login, /auth/refresh, /auth/forgot-password) con progressive delay e IP blocking
• NATS Auth Callout subscriber su $SYS.REQ.USER.AUTH: autorizza gli utenti NATS riusando le stesse policy applicative
• Integrazione con node-user-profiling per ruoli, scope e profilazione contestuale (device, geo, behavior)
• Audit logging strutturato per ogni evento di sicurezza (login, refresh, logout, lockout, revoca) con correlation ID

Architettura

Stack: Fastify v5 · Inversify (DI con constructor injection) · PostgreSQL via driver pg · Redis (sessioni, rate limiting, blocklist) · jose per JWT/JWS/JWE · @fastify/cookie per i cookie firmati · bcrypt per gli hash legacy migrati · speakeasy per TOTP · device-detector-js + geoip-lite per il contesto Zero Trust · @pzeta/fastify-utils (security, errorHandler, openapi plugins) · @pzeta/node-user-auth (schemi Zod condivisi con i consumer) · @pzeta/log per logging correlato.

Layout DDD (src/):

Pattern adottati: multi-strategia di autenticazione orchestrata da AuthMiddleware, Repository, Token Rotation con famiglia, Singleton thread-safe per la configurazione, Claim Provider Registry per arricchire i JWT (estensibile da plugin esterni), Circuit Breaker sulle chiamate a node-user-profiling, Audit Trail su PostgreSQL.

Flusso nginx auth_request: il browser richiede https://ditta.pzeta.it/orchestrator/foo → l'ingress nginx esegue una subrequest interna verso GET /user-auth/nginx/auth → il controller NginxAuthController valida cookie jwt_token/refresh_token, se necessario esegue refresh inline e propaga il nuovo cookie via X-Auth-Set-Cookie (che nginx rimette nella response originale), poi risponde 200 con header X-Auth-User, X-Auth-User-ID, X-Auth-Session-ID → nginx legge gli header, li propaga al backend (proxy_set_header) e instrada la richiesta a node-orchestrator. In caso di sessione assente o invalida la risposta è 401 e nginx restituisce un redirect a /login. La cache di auth_request deve essere ≤30 s o disabilitata, altrimenti maschera la scadenza del cookie e impedisce il refresh trasparente.

Casi d'uso

• Login utente da Vue (cookie JWT): il frontend chiama POST /user-auth/auth/login con credenziali → il servizio valida l'identità presso il provider esterno (OIDC) o presso node-user-profiling, materializza una sessione su Redis ed emette i cookie HttpOnly jwt_token e refresh_token. Tutte le chiamate successive dal browser verso qualsiasi servizio del namespace passano dal auth_request, che riconosce i cookie e propaga gli header al backend.
• Subrequest nginx per microservizi protetti: ogni ingress di node-orchestrator, node-storage, node-notification, ecc. ha auth_request /nginx/auth configurato verso questo servizio; nessun altro microservizio implementa logica di auth — si limita a leggere X-Auth-User-ID dagli header iniettati.
• M2M con OAuth2 Client Credentials: node-scheduler o un modulo orchestratore esterno richiede un access token a POST /user-auth/oauth/token con grant_type=client_credentials; il token JWT firmato viene poi verificato dal microservizio destinazione tramite la chiave pubblica esposta su JWKS, oppure introspettato su POST /user-auth/oauth/introspect.
• API key per integrazioni dev/test: uno script di seed o un test E2E imposta l'header x-api-key; le chiavi sono configurate via env (API_KEYS) e mappano a un utente fittizio con scope ristretti — utile in pipeline CI e per debug locale senza coinvolgere il provider esterno.
• Autenticazione NATS: i client NATS dei microservizi PZeta non si autenticano con credenziali statiche; quando aprono la connessione al broker, NATS pubblica una richiesta su $SYS.REQ.USER.AUTH che NatsAuthCalloutService consuma, verifica il JWT presentato e risponde con i permessi pub/sub appropriati per quel servizio.
• MFA per utenti privilegiati: gli admin abilitano TOTP via POST /auth/mfa/setup; il login successivo richiede un secondo step che valida il codice prima di emettere i cookie di sessione.

Identità & esposizione

Endpoint operazionali

Endpoint convenzionali esposti da tutti i microservizi PZeta basati su @pzeta/fastify-utils:

A questi si aggiungono, specifici per il dominio auth:

Configurazione

Variabili d'ambiente che un integratore deve conoscere (per la lista completa vedi config/example.env del repo):

FORBIDDEN: nessuna variabile contiene o accetta password utente in chiaro. Le credenziali primarie sono delegate all'Identity Provider esterno; questo servizio gestisce solo claim, hash di tecnologia (cookie secret, JWT secret) e configurazione di sicurezza.

Note eventing NATS

Il servizio è esclusivamente subscriber di sistema: si registra su $SYS.REQ.USER.AUTH (subject di sistema riservato a NATS Auth Callout) e risponde sincronicamente con le claim del client che sta tentando di connettersi al broker. Non pubblica eventi applicativi propri — l'auth callout sostituisce, su NATS, il ruolo che il subrequest svolge per HTTP.

I consumer non si "sottoscrivono" a questo servizio: lo invocano via HTTP o, indirettamente, via il broker. Per questo motivo lo scanner statico riporta zero publishes e un solo subscribe di sistema.

Dipendenze e dipendenti

Dipende da (servizi che questo servizio chiama):

• node-user-profiling

Consumato da (chi chiama questo servizio):

• node-orchestrator
• node-notification
• node-storage
• node-print
• node-renderer
• node-scheduler
• node-excel-export
• node-excel-import
• node-xmlvalidation
• node-postgrest-sidecar
• ingress nginx (auth_request)

Infrastruttura (PostgreSQL, NATS, Redis, MinIO) non è elencata qui — vedi sezione Architettura del singolo servizio.