Sicurezza e permessi

Autenticazione di sessione, CSRF, JWT, header di sicurezza, e il modello di permessi resource:action.

Sicurezza e permessi

Flusso di login

sequenceDiagram
    participant Form as Login Form
    participant Auth as Auth.bx doLogin()
    participant Sec as SecurityService
    participant Store as cbauth / Session Cache

    Form->>+Auth: POST /login (email + password)
    Auth->>Auth: CSRF check + cbvalidation
    Auth->>+Sec: authenticate( email, password )
    Sec->>Sec: bcrypt verify
    Sec->>+Store: cbauth.login() — write session
    Store-->>-Sec: ok
    Sec-->>-Auth: authenticated user
    Auth-->>-Form: redirect → /dashboard

Layout di autenticazione

Il flusso di autenticazione può usare uno dei due layout inclusi tramite l'impostazione cbLoginLayout:

Scegli Auth Center o Auth Split sulla pagina /settings. Il layout selezionato si applica alle pagine di login, registrazione, attivazione invito, e recupero password. Vedi Impostazioni dell'app per i file di layout e le istruzioni per layout personalizzati.

Single sign-on

cbSSO è abilitato tramite app/config/modules/cbsso.bx. Usa cbauth come autorità di sessione, quindi il login locale con password, le passkey, e l'SSO condividono la stessa sessione e le stesse regole di autorizzazione. La pagina di login renderizza un link per ogni provider configurato.

Google è il provider di esempio incluso. Imposta questi valori in .env dopo aver registrato l'URL di callback /cbsso/auth/Google presso Google:

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=https://example.com/cbsso/auth/Google

Abilitare e disabilitare l'SSO

Non esiste un'impostazione separata SSO_ENABLED. L'interruttore effettivo del provider è in app/config/modules/cbsso.bx: cbGenesis registra Google solo quando GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, e GOOGLE_REDIRECT_URI sono tutti popolati. Per disabilitare l'SSO Google, cancella uno qualsiasi di quei valori e riavvia o reinizializza l'applicazione. Il provider non apparirà più sulle pagine di login o profilo.

Non confondere questo con enableCBAuthIntegration: false. Quell'impostazione disabilita il listener generico opzionale cbauth di cbSSO; cbGenesis usa il proprio interceptor SSOAuthorization così può far rispettare il collegamento account locale, il provisioning, la corrispondenza delle identità, e le regole di audit. Vedi la documentazione di cbSSO per configurazione, gestione della risposta dell'identity provider, punti di intercettazione, e integrazione cbauth.

box migrate up

https://your-domain.example/cbsso/auth/Google

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=https://your-domain.example/cbsso/auth/Google

CBSSO_AUTO_PROVISION=true
CBSSO_ALLOWED_DOMAINS=example.com,example.org

Dopo la configurazione, le identità vengono abbinate per provider e soggetto immutabile, mai per sola email. Gli account locali esistenti devono essere esplicitamente collegati prima di poter essere usati tramite l'SSO.

Per deployment SAML in cluster, configura samlRequestCacheName di cbSSO su una regione CacheBox distribuita invece di usare la cache di replay in-memory predefinita.

Come cbSSO diventa una sessione locale

cbSSO possiede il protocollo del provider e la validazione del callback. cbGenesis possiede la decisione che segue: a quale account locale appartiene l'identità verificata, se può essere approvvigionata o collegata, e come diventa una sessione applicativa autenticata.

flowchart LR
    Browser[Browser] --> Start[cbSSO start route]
    Start --> Provider[Identity provider]
    Provider --> Callback[cbSSO callback route]
    Callback --> Authorize[cbSSO Auth.authorize]
    Authorize --> Event[CBSSOAuthorization]
    Event --> Interceptor[SSOAuthorization.bx]
    Interceptor --> UserService[UserService]
    UserService --> Identity[(SSO identity records)]
    Interceptor --> Security[SecurityService.loginSSO]
    Security --> Session[(cbauth session)]
    Session --> Browser

L'applicazione registra app/interceptors/SSOAuthorization.bx per il punto di intercettazione documentato CBSSOAuthorization di cbSSO. Il payload del callback contiene la risposta del provider verificata e il provider che l'ha gestita. L' interceptor segue quindi uno dei due percorsi di proprietà dell'applicazione:

sequenceDiagram
    participant C as cbSSO callback
    participant I as SSOAuthorization
    participant U as UserService
    participant S as SecurityService
    participant A as AuditLogService

    C->>I: CBSSOAuthorization(response, provider)
    alt Link intent
        I->>I: Verify logged-in user and matching session intent
        I->>U: linkSSOIdentity(user, response, provider)
        U-->>I: Linked identity
        I->>A: Record link success
    else Login intent
        I->>U: findBySSO(response, provider)
        alt No local identity and provisioning allowed
            I->>U: createFromSSO(response, provider)
        end
        I->>U: updateFromSSO(user, response, provider)
        I->>S: loginSSO(user)
        S-->>I: cbauth session established
        I->>A: Record login or provisioning success
    end
    I-->>C: Store success or failure result for completion flow

Perché esiste questo interceptor

cbSSO fornisce anche un listener di integrazione cbAuth generico. cbGenesis imposta intenzionalmente enableCBAuthIntegration: false in app/config/modules/cbsso.bx, perché il listener generico non può far rispettare le regole di identità e sicurezza degli account dell'applicazione. L'interceptor personalizzato è responsabile di:

• Abbinare le identità per provider e soggetto immutabile, mai per sola email.
• Richiedere una sessione autenticata e un intento corrispondente per il collegamento dell'account.
• Applicare la policy di provisioning e di dominio consentito prima di creare utenti.
• Mantenere i percorsi di autenticazione con password locale, remember-me, passkey, e SSO sotto la stessa autorità di sessione cbauth.
• Registrare le operazioni SSO riuscite e fallite nel registro di audit.

Questa separazione è deliberata: cbSSO verifica chi il provider dice che sia l'utente; cbGenesis decide cosa quell'identità è autorizzata a fare in questa applicazione.

Per il contratto upstream e l'integrazione generica alternativa, vedi la documentazione punti di intercettazione di cbSSO, gestione della risposta dell'identity provider, e integrazione cbAuth.

Livelli di sicurezza

Rate limiting

app/interceptors/RateLimiter.bx si attiva su preProcess - prima del routing, prima che qualsiasi handler venga eseguito - e limita cinque endpoint Auth non autenticati per IP client:

• doLogin, doRegister, doForgotPassword, doResetPassword, doActivateInvitation

Un chiamante che supera il limite viene reindirizzato al form con un errore flash; la richiesta non raggiunge mai l'handler, quindi una password corretta inviata mentre si è bloccati non fa comunque accedere l'utente.

Tutte e tre sono modificabili in /settings come qualsiasi altra impostazione dell'app - vedi Impostazioni dell'app.

Come funziona il conteggio

RateLimitService.attempt() è una finestra scorrevole: ogni tentativo, consentito o bloccato, reimposta la scadenza della chiave alla finestra completa da quel momento. Una chiave si raffredda solo una volta che resta silenziosa per un'intera finestra - il che continua a bloccare finché un attacco continua, piuttosto che riaprirsi a metà strada. Ogni endpoint ha il proprio contatore (con chiave event:ip), quindi esaurire il limite di login non influisce sulla registrazione o sul reset password.

Configurazione di cbsecurity

app/config/modules/cbsecurity.bx è l'unica fonte di verità per il firewall:

{
    authentication : {
        provider          : "authenticationService@cbauth",
        prcUserVariable   : "authUser"
    },
    firewall : {
        autoLoadFirewall         : true,
        validator                 : "CBAuthValidator@cbsecurity",
        handlerAnnotationSecurity : true,
        invalidAuthenticationEvent : "login",
        invalidAuthorizationEvent  : "dashboard.notAuthorized",
        rules                      : [] // authorization is annotation-based, not rule-based
    }
}

• prcUserVariable: "authUser" — l'utente autenticato è sempre disponibile come prc.authUser in ogni handler, vista, e layout.
• handlerAnnotationSecurity: true — questo è ciò che fa sì che le annotazioni @secured su una classe handler o un'azione applichino effettivamente qualcosa.
• rules: [] — questa app fa tutta la sua autorizzazione tramite annotazioni sugli handler, non tramite l'elenco alternativo di regole basate su pattern URL di cbsecurity.

Modello di permessi

Ogni permesso è uno slug nella forma resource:action, seminato da resources/database/seeds/AdminData.bx:

Applicalo sull'handler — questo è il vero confine di sicurezza, risolto dal CBAuthValidator di cbsecurity contro i permessi dell'utente autenticato:

@secured( "roles:admin,roles:read" )     // class-level: applies to index and any action without its own annotation
class extends="BaseSecureHandler" {

    @secured( "roles:admin,roles:write" )
    function create( event, rc, prc ) { ... }

    @secured( "roles:admin,roles:delete" )
    function delete( event, rc, prc ) { ... }

}

Un elenco separato da virgole è un controllo OR — basta uno qualsiasi dei permessi elencati.

Rispecchialo nella vista — solo per UX, mai il confine di sicurezza da solo. User.bx espone hasPermission() su prc.authUser, disponibile in qualsiasi vista o layout renderizzato tramite un handler protetto:

<bx:if prc.authUser.hasPermission( "roles:write,roles:admin" )>
    <button type="button" class="btn btn-primary" @click="openCreate()">New Role</button>
</bx:if>

hasPermission() accetta una stringa, un elenco separato da virgole, o un array e fa un controllo OR; hasAllPermissions() fa l'equivalente AND. Entrambi sono messi in cache per richiesta tramite getAllPermissions(), che unisce i permessi à-la-carte di un utente con ogni permesso concesso tramite i suoi ruoli. Ogni vista admin esistente (navigazione sidebar, Users/Roles/Permissions/Settings) segue già questo pattern — trattalo come il template per nuovi moduli protetti.

Un utente che fallisce un controllo @secured viene reindirizzato:

• Non autenticato → login
• Autenticato, permesso mancante → dashboard.notAuthorized

Servizi di sicurezza correlati

Problemi noti

"Questo è un dominio non valido" quando si registra una passkey

Le passkey sono configurate per il dominio localhost durante lo sviluppo locale. Se apri l'applicazione con un indirizzo IP come http://127.0.0.1:8080, WebAuthn tratta quello come un'origine diversa e rifiuta la registrazione con "Questo è un dominio non valido."

Apri invece l'applicazione su http://localhost:8080. Le passkey registrate per un'origine non sono intercambiabili con un'altra, quindi elimina e registra di nuovo la passkey se è stata creata mentre si usava un nome host diverso.