Sécurité & Permissions

Authentification de session, CSRF, JWT, en-têtes de sécurité, et le modèle de permissions resource:action.

Sécurité & Permissions

Flux de connexion

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

Mises en page d'authentification

Le flux d'authentification peut utiliser l'une ou l'autre des mises en page livrées via le paramètre cbLoginLayout :

Choisissez Auth Center ou Auth Split sur la page /settings. La mise en page sélectionnée s'applique aux pages de connexion, d'inscription, d'activation d'invitation, et de récupération de mot de passe. Voir Paramètres de l'application pour les fichiers de mise en page et les instructions de personnalisation.

Authentification unique

cbSSO est activé via app/config/modules/cbsso.bx. Il utilise cbauth comme autorité de session, si bien que la connexion locale par mot de passe, les passkeys, et le SSO partagent la même session et les mêmes règles d'autorisation. La page de connexion affiche un lien pour chaque fournisseur configuré.

Google est le fournisseur d'exemple livré. Définissez ces valeurs dans .env après avoir enregistré l'URL de callback /cbsso/auth/Google auprès de Google :

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

Activer et désactiver le SSO

Il n'existe pas de paramètre SSO_ENABLED séparé. Le commutateur de fournisseur effectif se trouve dans app/config/modules/cbsso.bx : cbGenesis n'enregistre Google que lorsque GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, et GOOGLE_REDIRECT_URI sont toutes renseignées. Pour désactiver le SSO Google, videz l'une de ces valeurs et redémarrez ou réinitialisez l'application. Le fournisseur n'apparaîtra plus sur les pages de connexion ou de profil.

Ne confondez pas ceci avec enableCBAuthIntegration: false. Ce paramètre désactive l'écouteur cbauth générique optionnel de cbSSO ; cbGenesis utilise son propre intercepteur SSOAuthorization afin de pouvoir imposer ses propres règles de liaison de compte local, de provisionnement, de correspondance d'identité, et d'audit. Voir la documentation de cbSSO pour la configuration, le traitement de la réponse du fournisseur d'identité, les points d'interception, et l'intégration 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

Après la configuration, les identités sont mises en correspondance par fournisseur et sujet immuable, jamais par email seul. Les comptes locaux existants doivent être explicitement liés avant de pouvoir être utilisés via SSO.

Pour les déploiements SAML en cluster, configurez le samlRequestCacheName de cbSSO vers une région CacheBox distribuée au lieu d'utiliser le cache de rejeu en mémoire par défaut.

Comment cbSSO devient une session locale

cbSSO possède le protocole du fournisseur et la validation du callback. cbGenesis possède la décision qui suit : à quel compte local l'identité vérifiée appartient, si elle peut être provisionnée ou liée, et comment elle devient une session applicative authentifiée.

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'application enregistre app/interceptors/SSOAuthorization.bx pour le point d'interception documenté CBSSOAuthorization de cbSSO. La charge utile du callback contient la réponse du fournisseur vérifiée et le fournisseur qui l'a traitée. L'intercepteur suit ensuite l'un des deux chemins gérés par l'application :

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

Pourquoi cet intercepteur existe

cbSSO fournit aussi un écouteur d'intégration cbAuth générique. cbGenesis définit intentionnellement enableCBAuthIntegration: false dans app/config/modules/cbsso.bx, car l'écouteur générique ne peut pas imposer les règles de sécurité d'identité et de compte de l'application. L'intercepteur personnalisé est responsable de :

• Faire correspondre les identités par fournisseur et sujet immuable, jamais par email seul.
• Exiger une session authentifiée et une intention correspondante pour la liaison de compte.
• Appliquer la politique de provisionnement et de domaines autorisés avant de créer des utilisateurs.
• Maintenir les chemins d'authentification par mot de passe local, se souvenir de moi, passkey, et SSO sous la même autorité de session cbauth.
• Enregistrer les opérations SSO réussies et échouées dans le journal d'audit.

Cette séparation est délibérée : cbSSO vérifie qui le fournisseur dit que l'utilisateur est ; cbGenesis décide ce que cette identité est autorisée à faire dans cette application.

Pour le contrat en amont et l'intégration générique alternative, voir la documentation des points d'interception cbSSO, du traitement de la réponse du fournisseur d'identité, et de l'intégration cbAuth.

Couches de sécurité

Limitation de débit

app/interceptors/RateLimiter.bx se déclenche sur preProcess - avant le routage, avant l'exécution de tout handler - et limite le débit de cinq points de terminaison Auth non authentifiés par IP client :

• doLogin, doRegister, doForgotPassword, doResetPassword, doActivateInvitation

Un appelant qui dépasse la limite est redirigé vers le formulaire avec une erreur flash ; la requête n'atteint jamais le handler, donc un mot de passe correct soumis pendant le blocage ne connecte quand même pas l'utilisateur.

Les trois sont modifiables sur /settings comme n'importe quel autre paramètre de l'application - voir Paramètres de l'application.

Comment fonctionne le comptage

RateLimitService.attempt() est une fenêtre glissante : chaque tentative, autorisée ou bloquée, réinitialise l'expiration de la clé à la fenêtre complète à partir de ce moment. Une clé ne se refroidit qu'une fois qu'elle reste silencieuse pendant une fenêtre entière - ce qui continue de bloquer tant que l'attaque se poursuit, plutôt que de se rouvrir à mi-chemin. Chaque point de terminaison a son propre compteur (indexé par event:ip), donc épuiser la limite de connexion n'affecte ni l'inscription ni la réinitialisation de mot de passe.

Configuration de cbsecurity

app/config/modules/cbsecurity.bx est la source unique de vérité pour le pare-feu :

{
    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'utilisateur authentifié est toujours disponible sous prc.authUser dans chaque handler, vue, et mise en page.
• handlerAnnotationSecurity: true — c'est ce qui fait que les annotations @secured sur une classe de handler ou une action appliquent réellement quelque chose.
• rules: [] — cette application effectue toute son autorisation via des annotations de handler, pas via la liste de règles alternative basée sur des motifs d'URL de cbsecurity.

Modèle de permissions

Chaque permission est un slug de la forme resource:action, seedé par resources/database/seeds/AdminData.bx :

Imposez-le sur le handler — c'est la véritable limite de sécurité, résolue par le CBAuthValidator de cbsecurity contre les permissions de l'utilisateur authentifié :

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

}

Une liste séparée par des virgules est un contrôle OU — une seule des permissions listées suffit.

Reflétez-le dans la vue — uniquement pour l'expérience utilisateur, jamais la limite de sécurité en elle-même. User.bx expose hasPermission() sur prc.authUser, disponible dans n'importe quelle vue ou mise en page rendue via un handler sécurisé :

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

hasPermission() accepte une chaîne, une liste séparée par des virgules, ou un tableau, et effectue un contrôle OU ; hasAllPermissions() fait l'équivalent en ET. Les deux sont mis en cache par requête via getAllPermissions(), qui fait l'union des permissions à la carte d'un utilisateur avec toutes les permissions accordées via ses rôles. Chaque vue d'administration existante (navigation de la barre latérale, Utilisateurs/Rôles/Permissions/Paramètres) suit déjà ce patron — traitez-le comme le modèle pour les nouveaux modules sécurisés.

Un utilisateur qui échoue à un contrôle @secured est redirigé :

• Non authentifié → login
• Authentifié, permission manquante → dashboard.notAuthorized

Services de sécurité associés

Problèmes connus

« This is an invalid domain » lors de l'enregistrement d'une passkey

Les passkeys sont configurées pour le domaine localhost pendant le développement local. Si vous ouvrez l'application avec une adresse IP telle que http://127.0.0.1:8080, WebAuthn considère cela comme une origine différente et rejette l'enregistrement avec « This is an invalid domain. »

Ouvrez plutôt l'application sur http://localhost:8080. Les passkeys enregistrées pour une origine ne sont pas interchangeables avec une autre, donc supprimez et réenregistrez la passkey si elle a été créée en utilisant un nom d'hôte différent.