Architettura

Questa pagina descrive come è strutturato Auris internamente e come i suoi componenti interagiscono. Comprendere l’architettura è utile per il debug di problemi di integrazione, la pianificazione dei confini di sicurezza o la valutazione di Auris per il deployment enterprise.

Panoramica di Alto Livello

Auris è una piattaforma a strati. La tua applicazione comunica con le API e gli SDK di Auris. Il livello API fornisce l’issuer di token nativo e i piani auth, e aggiunge autorizzazione, sicurezza e servizi per sviluppatori sopra di esso.

Auth planes (native Auris issuer + residual seams): token issuer (Auris-minted opaque tenant_id JWTs), session/logout (Auris authoritative; IdP end_session from DB; no /broker/ logout), IdP federation (native SP + TenantIdentityProvider / SsoConnection SoT; KC Admin sync/read gone), credential-store posture (IdP secrets in Auris DB). Hard isolation = opaque Tenant.id. Routing slug in iss /realms/<slug> is not an authz key. Not Keycloak-zero.

Modello Tenant

Ogni deployment Auris supporta più tenant. Un tenant è un ambiente completamente isolato con:

• Account utente e credenziali
• Applicazioni (client OAuth 2.0 registrati)
• Ruoli, permessi e policy di autorizzazione
• Configurazione di sicurezza (rate limit, policy MFA, regole IP, CAPTCHA)
• Template email, branding e domini personalizzati
• Log di audit ed endpoint webhook

Internamente, ogni tenant corrisponde direttamente a un tenant Auris (Tenant.id opaco). Ciò significa che l’isolamento del tenant è applicato a livello dell’identity store — gli utenti nel tenant A non possono autenticarsi sulle applicazioni del tenant B e i loro dati non vengono mai mescolati.

L’header x-tenant viene usato sulla maggior parte delle chiamate API Auris per identificare il contesto del tenant attivo. Gli SDK gestiscono questo automaticamente in base al domain (o identificatore del tenant) che configuri all’inizializzazione.

Autorizzazione a Tre Livelli

Auris implementa l’autorizzazione in tre livelli, ognuno più granulare del precedente:

Livello 1 — Autenticazione Auris (issuer JWT)

I token di accesso sono emessi e verificati da Auris (issuer nativo). La firma è HS256 (JWT_SECRET) di default, o RS256 quando configurato. tenant_id opaco è sempre presente sui token scoped al tenant. I token grezzi di IdP esterni non sono accettati per l’autorizzazione API (introspection Keycloak fail-closed).

Le claim includono iss (issuer Auris + /realms/<slug> per routing), sub, email, tenant_id, roles. Non assumere realm_access.roles.

Livello 2 — Prisma RBAC (Ruoli Fine-Grained con Permessi Tri-State)

Auris mantiene il proprio store di ruoli e permessi in PostgreSQL (tramite Prisma). Questo livello fornisce:

• Ruoli con un insieme denominato di permessi
• Permessi nel formato azione:risorsa (es. manage:users, view:invoices, approve:expenses)
• Valori permesso tri-state: ALLOW, DENY o INHERIT
  • ALLOW — concede esplicitamente il permesso
  • DENY — revoca esplicitamente, anche se un altro ruolo lo concede (DENY vince)
  • INHERIT — ricade sul ruolo padre o sul default del tenant
• Override permessi per utente che possono concedere o revocare permessi specifici indipendentemente dal ruolo
• Permessi con scope applicativo — lo stesso utente può avere permessi diversi in diverse applicazioni registrate

I controlli dei permessi avvengono lato server tramite POST /api/roles/check. La dashboard applica i permessi su ogni route API usando requirePermission(req, 'action:resource').

Livello 3 — FGA (Fine-Grained Authorization / Zanzibar-style ReBAC)

Il livello FGA implementa il controllo degli accessi basato sulle relazioni a livello di oggetto, ispirato al documento Zanzibar di Google. Risponde a domande come “può l’utente Alice leggere il documento 42?” o “è l’utente Bob un membro dell’organizzazione X?”.

Il modello FGA consiste in:

• Modello di Autorizzazione — uno schema (scritto in OpenFGA DSL) che definisce i tipi di oggetto e le relazioni tra di essi
• Tuple di Relazione — fatti archiviati nel database (es. document:42#viewer@user:alice)
• Motore di verifica — un algoritmo Zanzibar ricorsivo che valuta se un soggetto ha una relazione con un oggetto, seguendo le riscritture computedUserset e tuple-to-userset fino a una profondità configurabile (default: 25)

FGA supporta sei tipi di regole di riscrittura: this, computedUserset, tupleToUserset, union, intersection ed exclusion. Supporta anche expand (elenca tutti i soggetti per una relazione) e listObjects (elenca tutti gli oggetti a cui un soggetto ha accesso tramite ricerca inversa).

Quando FGA_ENGINE_ENABLED=true, i controlli di accesso alle risorse vengono indirizzati al motore FGA.

Tipi di Applicazione

Auris supporta quattro tipi di applicazioni, corrispondenti ai profili client OAuth 2.0 standard:

Ad ogni applicazione viene assegnato un Client ID (pubblico) e opzionalmente un Client Secret (per client riservati). I redirect URI sono registrati per applicazione e applicati esattamente — nessuna corrispondenza con caratteri jolly.

Flusso dei Token

Auris rilascia tre tipi di token seguendo le specifiche OpenID Connect:

Access Token

• Formato: JWT, default di codice JWT_ALGORITHM=HS256 (RS256 solo se configurato)
• Durata: JWT_EXPIRATION default 3600 s
• Contiene (mint Auris): iss, sub, email, tenant_id (opaco), realm / tenant_slug, roles, opzionali org_id, tenants
• Utilizzo: Authorization: Bearer <token>
• Verifica: solo HS256/RS256 locale (verifyJWT). Nessuna introspection Keycloak. JWKS solo sul path RS256

Refresh Token

• Formato: JWT con type: 'refresh' (non una stringa opaca)
• Durata: 30 giorni in createTokens
• Utilizzo: POST /api/auth/token grant refresh_token
• Sicurezza: rotazione a utilizzo singolo con detection di reuse

ID Token

• Formato: JWT, firmato con RS256
• Contiene: Claim di identità utente (name, email, picture, phone_number, locale, attributi personalizzati)
• Utilizzo: Usato dall’applicazione client per visualizzare le informazioni utente — non inviato alle API
• Verifica: Stesso endpoint JWKS dell’access token

OIDC Discovery

Auris pubblica un documento OIDC Discovery standard su:

GET /.well-known/openid-configuration

Login Hosted

Auris fornisce pagine di login hosted servite dal dominio Auris (o dal tuo dominio personalizzato). Queste pagine gestiscono il flusso OAuth 2.0 Authorization Code + PKCE end-to-end.

Tutti i livelli di sicurezza (CAPTCHA, rate limiting, protezione forza bruta, rilevamento login sospetti, MFA adattivo) vengono applicati durante il flusso di login hosted.

Motore Actions

Le Actions sono funzioni JavaScript personalizzate che vengono eseguite durante i flussi di autenticazione in un ambiente sandbox. Le Actions possono essere attivate in sei punti:

Architettura di Sicurezza

La sicurezza viene applicata a strati, dalla rete all’applicazione:

Rate Limiting

Quattro livelli di rate limit con contatori a finestra scorrevole:

Protezione Forza Bruta

I tentativi di login falliti vengono tracciati per account. Dopo una soglia configurabile (default: 5 fallimenti in 15 minuti), l’account viene temporaneamente bloccato.

CAPTCHA

Tre provider supportati: Cloudflare Turnstile, hCaptcha e Google reCAPTCHA v3.

Regole IP

Ogni tenant può definire regole di permesso e blocco basate su CIDR.

Rilevamento Login Sospetti

Dopo ogni autenticazione riuscita, Auris valuta cinque segnali di rischio: nuovo dispositivo, nuovo IP, nuovo paese, viaggio impossibile e IP VPN/proxy/datacenter.

DPoP Token Binding

Per le applicazioni che richiedono il massimo livello di sicurezza dei token, Auris supporta Demonstrating Proof of Possession (DPoP, RFC 9449).

Riepilogo Modello Dati

Le entità principali in Auris e le loro relazioni: