Seguridad y permisos

Autenticación de sesión, CSRF, JWT, encabezados de seguridad, y el modelo de permisos resource:action.

Seguridad y permisos

Flujo de inicio de sesión

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

Layouts de autenticación

El flujo de autenticación puede usar cualquiera de los dos layouts incluidos a través del ajuste cbLoginLayout:

Elige Auth Center o Auth Split en la página /settings. El layout seleccionado se aplica a las páginas de inicio de sesión, registro, activación de invitación, y recuperación de contraseña. Consulta Ajustes de la aplicación para los archivos de layout e instrucciones de layout personalizado.

Inicio de sesión único

cbSSO está habilitado a través de app/config/modules/cbsso.bx. Usa cbauth como la autoridad de sesión, de modo que el inicio de sesión local con contraseña, las passkeys, y SSO comparten la misma sesión y reglas de autorización. La página de inicio de sesión renderiza un enlace por cada proveedor configurado.

Google es el proveedor de ejemplo incluido. Establece estos valores en .env después de registrar la URL de callback /cbsso/auth/Google con Google:

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

Habilitar y deshabilitar SSO

No existe un ajuste SSO_ENABLED separado. El interruptor de proveedor efectivo está en app/config/modules/cbsso.bx: cbGenesis registra Google solo cuando GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, y GOOGLE_REDIRECT_URI están todos completados. Para deshabilitar el SSO de Google, borra cualquiera de esos valores y reinicia o reinicializa la aplicación. El proveedor ya no aparecerá en las páginas de inicio de sesión o perfil.

No confundas esto con enableCBAuthIntegration: false. Ese ajuste deshabilita el listener genérico opcional de cbauth de cbSSO; cbGenesis usa su propio interceptor SSOAuthorization para poder hacer cumplir la vinculación de cuentas local, el aprovisionamiento, la coincidencia de identidad, y las reglas de auditoría. Consulta la documentación de cbSSO sobre configuración, manejo de la respuesta del proveedor de identidad, puntos de intercepción, y integración con 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

Después de la configuración, las identidades se emparejan por proveedor y sujeto inmutable, nunca por solo el correo electrónico. Las cuentas locales existentes deben vincularse explícitamente antes de que puedan usarse a través de SSO.

Para despliegues SAML en clúster, configura samlRequestCacheName de cbSSO a una región de CacheBox distribuida en lugar de usar la caché de repetición en memoria predeterminada.

Cómo cbSSO se convierte en una sesión local

cbSSO posee el protocolo del proveedor y la validación del callback. cbGenesis posee la decisión que sigue: a qué cuenta local pertenece la identidad verificada, si puede ser aprovisionada o vinculada, y cómo se convierte en una sesión de aplicación autenticada.

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

La aplicación registra app/interceptors/SSOAuthorization.bx para el punto de intercepción documentado CBSSOAuthorization de cbSSO. La carga útil del callback contiene la respuesta verificada del proveedor y el proveedor que la manejó. El interceptor entonces sigue uno de dos caminos propiedad de la aplicación:

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

Por qué existe este interceptor

cbSSO también provee un listener de integración genérico cbAuth. cbGenesis deliberadamente establece enableCBAuthIntegration: false en app/config/modules/cbsso.bx, porque el listener genérico no puede hacer cumplir las reglas de identidad y seguridad de cuenta de la aplicación. El interceptor personalizado es responsable de:

• Emparejar identidades por proveedor y sujeto inmutable, nunca por solo el correo electrónico.
• Requerir una sesión autenticada y una intención coincidente para la vinculación de cuentas.
• Aplicar la política de aprovisionamiento y dominios permitidos antes de crear usuarios.
• Mantener las rutas de autenticación de contraseña local, recordarme, passkey, y SSO bajo la misma autoridad de sesión de cbauth.
• Registrar las operaciones de SSO exitosas y fallidas en el registro de auditoría.

Esta separación es deliberada: cbSSO verifica quién dice el proveedor que es el usuario; cbGenesis decide qué se le permite hacer a esa identidad en esta aplicación.

Para el contrato upstream y la integración genérica alternativa, consulta la documentación de puntos de intercepción de cbSSO, manejo de la respuesta del proveedor de identidad, e integración con cbAuth.

Capas de seguridad

Limitación de tasa

app/interceptors/RateLimiter.bx se dispara en preProcess - antes del enrutamiento, antes de que se ejecute cualquier handler - y limita cinco endpoints no autenticados de Auth por IP del cliente:

• doLogin, doRegister, doForgotPassword, doResetPassword, doActivateInvitation

Un llamante que excede el límite es redirigido de vuelta al formulario con un error flash; la solicitud nunca llega al handler, así que una contraseña correcta enviada mientras está bloqueado aún así no inicia sesión al usuario.

Los tres son editables en /settings como cualquier otro ajuste de la aplicación - consulta Ajustes de la aplicación.

Cómo funciona el conteo

RateLimitService.attempt() es una ventana deslizante: cada intento, permitido o bloqueado, reinicia la expiración de la clave a la ventana completa desde ese momento. Una clave solo se enfría una vez que permanece en silencio durante una ventana completa - lo que mantiene el bloqueo mientras dure un ataque, en lugar de reabrirse a mitad de camino. Cada endpoint tiene su propio contador (con clave event:ip), así que agotar el límite de inicio de sesión no afecta al registro ni al restablecimiento de contraseña.

Configuración de cbsecurity

app/config/modules/cbsecurity.bx es la única fuente de verdad para el 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" — el usuario autenticado siempre está disponible como prc.authUser en cada handler, vista, y layout.
• handlerAnnotationSecurity: true — esto es lo que hace que las anotaciones @secured en una clase de handler o acción realmente hagan cumplir algo.
• rules: [] — esta aplicación hace toda su autorización a través de anotaciones de handler, no de la lista alternativa de reglas basadas en patrones de URL de cbsecurity.

Modelo de permisos

Cada permiso es un slug en la forma resource:action, sembrado por resources/database/seeds/AdminData.bx:

Hazlo cumplir en el handler — este es el límite de seguridad real, resuelto por el CBAuthValidator de cbsecurity contra los permisos del usuario autenticado:

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

}

Una lista separada por comas es una comprobación de tipo OR — cualquiera de los permisos listados es suficiente.

Refléjalo en la vista — solo para UX, nunca el límite de seguridad por sí solo. User.bx expone hasPermission() en prc.authUser, disponible en cualquier vista o layout renderizado a través de un handler protegido:

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

hasPermission() acepta una cadena, una lista separada por comas, o un array, y hace una comprobación OR; hasAllPermissions() hace el equivalente AND. Ambos se cachean por solicitud vía getAllPermissions(), que une los permisos à-la-carte de un usuario con cada permiso otorgado a través de sus roles. Cada vista de administración existente (navegación de la barra lateral, Usuarios/Roles/Permisos/Configuración) ya sigue este patrón — trátalo como la plantilla para nuevos módulos protegidos.

Un usuario que falla una comprobación @secured es redirigido:

• No autenticado → login
• Autenticado, sin el permiso → dashboard.notAuthorized

Servicios de seguridad relacionados

Problemas conocidos

"This is an invalid domain" al registrar una passkey

Las passkeys están configuradas para el dominio localhost durante el desarrollo local. Si abres la aplicación con una dirección IP como http://127.0.0.1:8080, WebAuthn lo trata como un origen distinto y rechaza el registro con "This is an invalid domain."

Abre la aplicación en http://localhost:8080 en su lugar. Las passkeys registradas para un origen no son intercambiables con otro, así que elimina y vuelve a registrar la passkey si fue creada mientras usabas un nombre de host distinto.