Concetti Chiave

Questa pagina definisce i concetti fondamentali di Auris. Ogni termine è spiegato nel contesto di come Auris lo utilizza. Se sei nuovo alla gestione delle identità e degli accessi, leggere questa pagina prima delle guide renderà il resto della documentazione più facile da seguire.

Tenant

Un ambiente isolato in Auris. Ogni configurazione, utente, applicazione, ruolo e policy appartiene a un tenant. I tenant non possono condividere dati — un account utente nel tenant A non può autenticarsi su un’applicazione registrata nel tenant B.

Internamente, ogni tenant corrisponde a un realm Keycloak. Keycloak applica l’isolamento del realm a livello dell’identity store.

Nelle richieste API, il tenant attivo è identificato dall’header x-tenant. Gli SDK lo impostano automaticamente in base al domain configurato all’inizializzazione.

I deployment single-tenant usano un unico tenant (solitamente chiamato 'default'). I prodotti SaaS multi-tenant creano un tenant per ogni organizzazione cliente — questo è diverso dal concetto di Organization di Auris, che è un raggruppamento B2B all’interno di un unico tenant Auris.

Applicazione

Un client registrato con Auris. Ogni software che utilizza l’autenticazione Auris deve essere registrato come applicazione. Un’applicazione ha:

• Un Client ID unico (identificatore pubblico, sicuro da incorporare nel codice browser)
• Un Client Secret opzionale (privato, solo per client M2M lato server)
• Un elenco di Redirect URI consentiti (applicati esattamente — nessun carattere jolly)
• Un Tipo di Applicazione che determina i flussi OAuth 2.0 disponibili

Tipi di applicazione:

Utente

Un’identità gestita da Auris all’interno di un tenant. Gli utenti hanno:

• Un ID unico (claim sub nei JWT)
• Un indirizzo email (identificatore primario)
• Nome utente, nome, cognome e numero di telefono opzionali
• Uno o più ruoli (tramite assegnazioni di ruolo)
• Override di permessi opzionali (ALLOW o DENY su permessi specifici, indipendentemente dai ruoli)
• Uno o più metodi di autenticazione (password, account social, passkey, ecc.)
• Configurazioni 2FA opzionali (TOTP, SMS, WebAuthn)

Ruolo

Una raccolta denominata di permessi. Gli utenti vengono assegnati ai ruoli; i ruoli definiscono ciò che quegli utenti sono autorizzati a fare. I ruoli sono scoped a un tenant.

Un utente può avere più ruoli. Quando si verifica un permesso, tutti i ruoli vengono valutati — se qualsiasi ruolo concede ALLOW e nessuno concede DENY, il permesso viene accordato.

Permesso

Una capacità rappresentata come stringa azione:risorsa. Esempi:

• manage:users — accesso CRUD completo agli utenti
• view:invoices — accesso in lettura alle fatture
• approve:expenses — possibilità di approvare le note spese

I permessi hanno valori tri-state:

DENY vince sempre su ALLOW.

Access Token

Un JWT (JSON Web Token) di breve durata che prova l’identità dell’utente e porta i suoi permessi. Gli access token sono:

• Firmati con RS256 (RSA + SHA-256) usando la chiave privata di Auris
• Verificati da qualsiasi servizio con accesso all’endpoint JWKS pubblico di Auris
• Inviati nell’header HTTP Authorization: Bearer <token> alle API protette
• Di breve durata (default: 15 minuti — configurabile per tenant)

Refresh Token

Un token opaco di lunga durata usato per ottenere nuovi access token dopo la scadenza di quello corrente. I refresh token sono:

• Opachi — sono stringhe casuali, non JWT.
• Longevi (default: 7 giorni — configurabile per tenant)
• A utilizzo singolo — ogni volta che un refresh token viene usato, Auris invalida il vecchio e ne emette uno nuovo (rotazione del refresh token)

ID Token

Un token OpenID Connect (OIDC) contenente le informazioni del profilo dell’utente autenticato. Gli ID token sono:

• JWT, firmati con RS256 come gli access token
• Destinati all’applicazione client per visualizzare le informazioni utente
• Non inviati alle API — le API dovrebbero usare l’access token

PKCE

Proof Key for Code Exchange (RFC 7636). Un’estensione di sicurezza al flusso Authorization Code di OAuth 2.0 che previene gli attacchi di intercettazione del codice di autorizzazione.

Auris applica S256 (hashing SHA-256) — il PKCE plain non è accettato. Tutti gli SDK Auris gestiscono la generazione e verifica PKCE automaticamente.

RBAC

Role-Based Access Control. Il modello di permessi in cui:

• Gli utenti vengono assegnati a ruoli
• I ruoli hanno permessi
• I permessi controllano l’accesso ad azioni e risorse

In Auris, RBAC è implementato come Livello 2 del modello di autorizzazione a tre livelli.

FGA

Fine-Grained Authorization. Un sistema di controllo degli accessi basato sulle relazioni in stile Zanzibar per i permessi a livello di oggetto. FGA risponde alla domanda: “Può questo utente specifico accedere a questo oggetto specifico?”

FGA usa tre concetti fondamentali:

• Modello di Autorizzazione — uno schema che definisce tipi di oggetto e relazioni
• Tuple di Relazione — fatti archiviati nel database
• Verifica — una query ricorsiva che determina se un soggetto ha una relazione con un oggetto

SSO

Single Sign-On. Un meccanismo che permette agli utenti di autenticarsi una volta con un identity provider (IdP) e ottenere automaticamente accesso a più applicazioni.

Auris supporta due protocolli SSO:

• SAML 2.0 — protocollo basato su XML ampiamente usato dagli IdP enterprise (Okta, Azure AD, ADFS)
• OIDC (OpenID Connect) — protocollo moderno basato su JSON

SCIM

System for Cross-domain Identity Management (RFC 7643/7644). Un protocollo standard per il provisioning e deprovisioning automatizzato degli utenti.

Con SCIM abilitato:

• Quando le HR creano un nuovo dipendente in Okta o Azure AD, quell’utente viene automaticamente provisioned in Auris
• Quando un dipendente viene licenziato, il suo account Auris viene automaticamente deprovisioned

M2M

Machine-to-Machine. Autenticazione server-to-server in cui non è coinvolto nessun utente umano. Utilizza il grant Client Credentials di OAuth 2.0.

MFA

Multi-Factor Authentication. Richiedere agli utenti di provare la loro identità con più di un fattore. Auris supporta tre metodi MFA:

Actions

Funzioni JavaScript personalizzate che vengono eseguite durante i flussi di autenticazione in un ambiente sandbox. Le Actions ti permettono di estendere il comportamento di Auris.

Organizzazione

Un’entità B2B all’interno di un tenant. Le organizzazioni vengono usate quando costruisci un prodotto che vendi ad altre aziende — ogni tuo cliente è modellato come un’Organizzazione.

Dominio Personalizzato

Una funzionalità che ti permette di servire le pagine di login hosted di Auris dal tuo dominio (es. auth.tuaazienda.com).

Webhook

Una callback HTTP che Auris invia al tuo server quando si verificano eventi specifici. I webhook sono firmati con HMAC-SHA256.

OIDC Discovery

Il meccanismo standard per cui i client OIDC scoprono la configurazione di un identity provider. Auris pubblica il suo documento OIDC Discovery su:

GET /.well-known/openid-configuration