Segurança e Permissões

Autenticação por sessão, CSRF, JWT, cabeçalhos de segurança, e o modelo de permissões resource:action.

Segurança e Permissões

Fluxo de início de sessão

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 autenticação

O fluxo de autenticação pode utilizar qualquer um dos dois layouts incluídos, através da definição cbLoginLayout:

Escolha Auth Center ou Auth Split na página /settings. O layout selecionado aplica-se ao início de sessão, ao registo, à ativação de convites, e às páginas de recuperação de palavra-passe. Veja Definições da Aplicação para os ficheiros de layout e as instruções de personalização.

Single sign-on

O cbSSO é ativado através de app/config/modules/cbsso.bx. Utiliza o cbauth como autoridade de sessão, pelo que o início de sessão local por palavra-passe, as passkeys, e o SSO partilham a mesma sessão e as mesmas regras de autorização. A página de início de sessão renderiza uma ligação para cada fornecedor configurado.

O Google é o fornecedor de exemplo incluído. Defina estes valores no .env depois de registar o URL de callback /cbsso/auth/Google junto do Google:

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

Ativar e desativar o SSO

Não existe uma definição separada SSO_ENABLED. O interruptor efetivo do fornecedor está em app/config/modules/cbsso.bx: o cbGenesis regista o Google apenas quando GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, e GOOGLE_REDIRECT_URI estão todos preenchidos. Para desativar o SSO com o Google, limpe qualquer um desses valores e reinicie ou reinicialize a aplicação. O fornecedor deixará de aparecer nas páginas de início de sessão ou de perfil.

Não confunda isto com enableCBAuthIntegration: false. Essa definição desativa o listener genérico e opcional do cbauth do cbSSO; o cbGenesis utiliza o seu próprio interceptor SSOAuthorization, para poder aplicar as regras locais de ligação de contas, criação de utilizadores, correspondência de identidade, e auditoria. Veja a documentação do cbSSO sobre configuração, tratamento da resposta do fornecedor de identidade, pontos de interceção, e integração com o 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

Após a configuração, as identidades são correspondidas pelo fornecedor e por um sujeito imutável, nunca apenas pelo e-mail. As contas locais existentes têm de ser explicitamente ligadas antes de poderem ser utilizadas através de SSO.

Para implantações SAML em cluster, configure o samlRequestCacheName do cbSSO para uma região distribuída do CacheBox, em vez de utilizar a cache de repetição em memória predefinida.

Como o cbSSO se torna numa sessão local

O cbSSO é dono do protocolo do fornecedor e da validação do callback. O cbGenesis é dono da decisão que se segue: a que conta local pertence a identidade verificada, se pode ser criada ou ligada, e como se torna numa sessão autenticada da aplicação.

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

A aplicação regista app/interceptors/SSOAuthorization.bx para o ponto de interceção documentado do cbSSO, CBSSOAuthorization. O payload do callback contém a resposta verificada do fornecedor e o fornecedor que a tratou. O interceptor segue então um de dois caminhos pertencentes à aplicação:

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

Porque existe este interceptor

O cbSSO também fornece um listener genérico de integração com o cbAuth. O cbGenesis define intencionalmente enableCBAuthIntegration: false em app/config/modules/cbsso.bx, porque o listener genérico não consegue aplicar as regras de identidade e segurança de conta da aplicação. O interceptor personalizado é responsável por:

• Corresponder identidades pelo fornecedor e por um sujeito imutável, nunca apenas pelo e-mail.
• Exigir uma sessão autenticada e uma intenção correspondente para a ligação de contas.
• Aplicar a política de criação de utilizadores e de domínios permitidos antes de criar utilizadores.
• Manter os percursos de autenticação local por palavra-passe, "lembrar-me", passkey, e SSO sob a mesma autoridade de sessão do cbauth.
• Registar as operações de SSO bem-sucedidas e falhadas no registo de auditoria.

Esta separação é deliberada: o cbSSO verifica quem o fornecedor diz que o utilizador é; o cbGenesis decide o que essa identidade pode fazer nesta aplicação.

Para o contrato a montante e a integração genérica alternativa, veja a documentação do cbSSO sobre pontos de interceção, tratamento da resposta do fornecedor de identidade, e integração com o cbAuth.

Camadas de segurança

Limitação de taxa

app/interceptors/RateLimiter.bx dispara em preProcess - antes do routing, antes de qualquer handler ser executado - e limita cinco endpoints não autenticados de Auth por IP do cliente:

• doLogin, doRegister, doForgotPassword, doResetPassword, doActivateInvitation

Quem chama e excede o limite é redirecionado de volta ao formulário com um erro flash; o pedido nunca chega ao handler, pelo que uma palavra-passe correta submetida enquanto bloqueado continua a não iniciar sessão do utilizador.

As três são editáveis em /settings, como qualquer outra definição da aplicação - veja Definições da Aplicação.

Como funciona a contagem

RateLimitService.attempt() é uma janela deslizante: a cada tentativa, permitida ou bloqueada, a expiração da chave é reposta para a janela completa a partir desse momento. Uma chave só arrefece depois de ficar em silêncio durante uma janela inteira - o que mantém o bloqueio enquanto um ataque continuar, em vez de reabrir a meio. Cada endpoint tem o seu próprio contador (indexado por event:ip), pelo que esgotar o limite de início de sessão não afeta o registo nem a reposição de palavra-passe.

Configuração do cbsecurity

app/config/modules/cbsecurity.bx é a única fonte de verdade para a 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" — o utilizador autenticado está sempre disponível como prc.authUser em todos os handlers, vistas, e layouts.
• handlerAnnotationSecurity: true — é isto que faz com que as anotações @secured numa classe ou ação de handler tenham, de facto, algum efeito.
• rules: [] — esta aplicação faz toda a sua autorização através de anotações nos handlers, e não através da lista alternativa de regras por padrão de URL do cbsecurity.

Modelo de permissões

Cada permissão é um slug na forma resource:action, semeado por resources/database/seeds/AdminData.bx:

Aplique-a no handler — esta é a verdadeira fronteira de segurança, resolvida pelo CBAuthValidator do cbsecurity contra as permissões do utilizador 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 ) { ... }

}

Uma lista separada por vírgulas é uma verificação OU — basta qualquer uma das permissões listadas.

Espelhe-a na vista — apenas para efeitos de UX, nunca como a fronteira de segurança por si só. User.bx expõe hasPermission() em prc.authUser, disponível em qualquer vista ou layout renderizado através de um 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() aceita uma string, uma lista separada por vírgulas, ou um array, e faz uma verificação OU; hasAllPermissions() faz o equivalente com E. Ambas são colocadas em cache por pedido via getAllPermissions(), que une as permissões à-la-carte de um utilizador com todas as permissões concedidas através das suas funções. Todas as vistas de administração existentes (navegação da barra lateral, Users/Roles/Permissions/Settings) já seguem este padrão — trate-o como o template para novos módulos protegidos.

Um utilizador que falhe numa verificação @secured é redirecionado:

• Não autenticado → login
• Autenticado, sem a permissão → dashboard.notAuthorized

Serviços de segurança relacionados

Problemas conhecidos

"This is an invalid domain" ao registar uma passkey

As passkeys estão configuradas para o domínio localhost durante o desenvolvimento local. Se abrir a aplicação com um endereço IP como http://127.0.0.1:8080, o WebAuthn trata-o como uma origem diferente e rejeita o registo com "This is an invalid domain."

Abra antes a aplicação em http://localhost:8080. As passkeys registadas para uma origem não são intercambiáveis com outra, pelo que deve eliminar e registar novamente a passkey se ela foi criada enquanto utilizava um nome de anfitrião diferente.