Security & Permissions

Session auth, CSRF, JWT, security headers, and the resource:action permission model.

Security & Permissions

Login flow

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

Authentication layouts

The authentication flow can use either shipped layout through the cbLoginLayout setting:

Choose Auth Center or Auth Split on the /settings page. The selected layout applies to login, registration, invitation activation, and password-recovery pages. See App Settings for the layout files and custom-layout instructions.

Single sign-on

cbSSO is enabled through app/config/modules/cbsso.bx. It uses cbauth as the session authority, so local password login, passkeys, and SSO share the same session and authorization rules. The login page renders a link for every configured provider.

Google is the shipped example provider. Set these values in .env after registering the callback URL /cbsso/auth/Google with Google:

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

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

After setup, identities are matched by provider and immutable subject, never by email alone. Existing local accounts must be explicitly linked before they can be used through SSO.

For clustered SAML deployments, configure cbSSO's samlRequestCacheName to a distributed CacheBox region instead of using the default in-memory replay cache.

How cbSSO becomes a local session

cbSSO owns the provider protocol and callback validation. cbGenesis owns the decision that follows: which local account the verified identity belongs to, whether it may be provisioned or linked, and how it becomes an authenticated application session.

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

The application registers app/interceptors/SSOAuthorization.bx for cbSSO's documented CBSSOAuthorization interception point. The callback payload contains the verified provider response and the provider that handled it. The interceptor then follows one of two application-owned paths:

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

Why this interceptor exists

cbSSO also provides a generic cbAuth integration listener. cbGenesis intentionally sets enableCBAuthIntegration: false in app/config/modules/cbsso.bx, because the generic listener cannot enforce the application's identity and account-security rules. The custom interceptor is responsible for:

• Matching identities by provider and immutable subject, never by email alone.
• Requiring an authenticated session and matching intent for account linking.
• Applying the provisioning and allowed-domain policy before creating users.
• Keeping local password, remember-me, passkey, and SSO authentication paths under the same cbauth session authority.
• Recording successful and failed SSO operations in the audit trail.

This separation is deliberate: cbSSO verifies who the provider says the user is; cbGenesis decides what that identity is allowed to do in this application.

For the upstream contract and the alternative generic integration, see the cbSSO interception points, identity-provider response handling, and cbAuth integration documentation.

Security layers

Rate limiting

app/interceptors/RateLimiter.bx fires on preProcess - before routing, before any handler runs - and throttles five unauthenticated Auth endpoints by client IP:

• doLogin, doRegister, doForgotPassword, doResetPassword, doActivateInvitation

A caller that exceeds the limit is redirected back to the form with a flash error; the request never reaches the handler, so a correct password submitted while blocked still does not log the user in.

All three are editable at /settings like any other app setting - see App Settings.

cbsecurity configuration

app/config/modules/cbsecurity.bx is the single source of truth for the 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" — the authenticated user is always available as prc.authUser in every handler, view, and layout.
• handlerAnnotationSecurity: true — this is what makes @secured annotations on a handler class or action actually enforce anything.
• rules: [] — this app does all of its authorization via handler annotations, not cbsecurity's alternative URL-pattern rule list.

Permission model

Every permission is a slug in the form resource:action, seeded by resources/database/seeds/AdminData.bx:

Enforce it on the handler — this is the real security boundary, resolved by cbsecurity's CBAuthValidator against the authenticated user's permissions:

@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 ) { ... }

}

A comma-separated list is an OR check — any one of the listed permissions is enough.

Mirror it in the view — UX only, never the security boundary on its own. User.bx exposes hasPermission() on prc.authUser, available in any view or layout rendered through a secured handler:

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

hasPermission() accepts a string, comma-list, or array and does an OR check; hasAllPermissions() does the AND equivalent. Both are cached per-request via getAllPermissions(), which unions a user's à-la-carte permissions with every permission granted through their roles. Every existing admin view (sidebar nav, Users/Roles/Permissions/Settings) already follows this pattern — treat it as the template for new secured modules.

A user who fails an @secured check is redirected:

• Unauthenticated → login
• Authenticated, missing permission → dashboard.notAuthorized

Related security services

Known issues

"This is an invalid domain" when registering a passkey

Passkeys are configured for the localhost domain during local development. If you open the application with an IP address such as http://127.0.0.1:8080, WebAuthn treats that as a different origin and rejects the registration with "This is an invalid domain."

Open the application at http://localhost:8080 instead. Passkeys registered for one origin are not interchangeable with another, so delete and register the passkey again if it was created while using a different host name.