Enterprise Security Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require 3brs/enterprise-security-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       EnterpriseSecurityBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console enterprise-security:install
   

   Update config/packages/enterprise_security.yaml to bind to your user entity (e.g., App\Entity\User):

   enterprise_security:
       user_entity: App\Entity\User
       password_policy:
           min_length: 12
   

3. First Use Case: Password Policy Validation Use the validator in a form type:

   use EnterpriseSecurityBundle\Validator\Constraints\PasswordPolicy;
   
   $builder->add('plainPassword', TextType::class, [
       'constraints' => [new PasswordPolicy()]
   ]);
   

Implementation Patterns

Core Workflows

1. Authentication Flows

• Magic Links Trigger via a service:

  $this->magicLinkService->sendLoginLink($user->getEmail());
  

  Handle the callback route with:

  $this->magicLinkHandler->validateAndAuthenticate($token);
  

• OAuth Integration Configure providers in enterprise_security.yaml:

  oauth:
      google:
          client_id: '%env(GOOGLE_CLIENT_ID)%'
          client_secret: '%env(GOOGLE_CLIENT_SECRET)%'
  

  Use the authenticator:

  $this->oauthAuthenticator->authenticate('google', $code);
  

2. Session & IP Management

• IP Whitelisting Middleware example:

  $this->ipWhitelistMiddleware->allow(['192.168.1.0/24']);
  $this->ipWhitelistMiddleware->deny(['10.0.0.5']);
  

• Session Tracking Log events via:

  $this->sessionTracker->logActivity($user, 'login', ['ip' => $request->getClientIp()]);
  

3. Password Management

• Runtime Policy Enforcement

  $this->passwordPolicy->validate($plainPassword, $user);
  $this->passwordHistory->add($user, $plainPassword);
  

• Expiration Handling Check in a listener:

  if ($this->passwordExpiration->isExpired($user)) {
      $this->passwordExpiration->forceReset($user);
  }
  

4. GDPR Compliance

• Self-Service Deletion Route to a controller:

  $this->gdprService->deleteAccount($user, $request->request->get('confirm'));
  

Integration Tips

Symfony Security Integration

• Custom Authenticator Extend AbstractAuthenticator and use bundle services:

  use EnterpriseSecurityBundle\Security\Authenticator\MagicLinkAuthenticator;
  
  class CustomAuthenticator extends MagicLinkAuthenticator { ... }
  

• Firewall Configuration

  security:
      firewalls:
          main:
              custom_authenticators:
                  - App\Security\CustomAuthenticator
              enterprise_security:
                  - magic_link
                  - oauth
  

Event Listeners

• Post-Authentication

  $this->eventDispatcher->dispatch(new PostAuthenticateEvent($user, $token));
  

• Password Reset

  $this->eventDispatcher->dispatch(new PasswordResetEvent($user));
  

Runtime Configuration

• Dynamic Settings Override via a service:

  services:
      App\Service\SecurityConfigOverride:
          decorates: 'enterprise_security.config'
          arguments: ['@enterprise_security.config.inner']
  

Gotchas and Tips

Pitfalls

1. Entity Binding

   • Issue: Forgetting to set user_entity in config causes NullReferenceException.
   • Fix: Always validate config/packages/enterprise_security.yaml after installation.

2. OAuth State Management

   • Issue: Missing state parameter in OAuth redirects can lead to CSRF vulnerabilities.
   • Fix: Use the bundle’s built-in state generator:

     $state = $this->oauthStateGenerator->generate();
     

3. Password History Collisions

   • Issue: Hashing collisions may bypass history checks.
   • Fix: Use the bundle’s PasswordHistory with a secure hashing strategy (e.g., Argon2).

4. Session Fixation

   • Issue: Reusing session IDs across logins.
   • Fix: Regenerate sessions post-authentication:

     $this->sessionRegenerator->regenerate($request);
     

5. Rate Limiting Quirks

   • Issue: IP-based rate limiting may block legitimate traffic.
   • Fix: Combine with user-agent checks:

     account_lockout:
         rate_limiting:
             by_ip: true
             by_user_agent: true
     

Debugging

1. Enable Verbose Logging

   enterprise_security:
       debug: true
   

   Logs appear in var/log/dev.log.

2. Event Debugging

   • Dump events in a listener:

     use Symfony\Component\EventDispatcher\GenericEvent;
     
     public function onKernelRequest(GenericEvent $event) {
         dump($event->getArgument('security_events'));
     }
     

3. Token Validation

   • For magic links/OAuth, validate tokens manually:

     $this->tokenValidator->validate($token);
     

Extension Points

1. Custom Validators Extend AbstractValidator:

   use EnterpriseSecurityBundle\Validator\AbstractValidator;
   
   class CustomPasswordValidator extends AbstractValidator {
       protected function validatePassword($password, $user) {
           // Custom logic
       }
   }
   

2. Event Subscribers Create a subscriber for PostAuthenticateEvent:

   use EnterpriseSecurityBundle\Event\PostAuthenticateEvent;
   
   class CustomAuthEventSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [PostAuthenticateEvent::class => 'onPostAuthenticate'];
       }
   
       public function onPostAuthenticate(PostAuthenticateEvent $event) {
           // Custom logic
       }
   }
   

3. Config Overrides Decorate the config service to modify settings at runtime:

   $this->config->override('password_policy.min_length', 14);
   

4. WebAuthn Customization Extend PasskeyService for custom RPs (Relying Parties):

   $this->passkeyService->setRpName('MyApp');
   $this->passkeyService->setRpId('myapp.example.com');
   

Performance Tips

1. Cache Token Validation

   enterprise_security:
       token_validation:
           cache: true
           cache_ttl: 3600
   

2. Batch IP Checks For bulk operations, use:

   $this->ipValidator->validateBatch([$ip1, $ip2, $ip3]);
   

3. Lazy-Load User Data Avoid eager-loading sensitive fields in queries:

   $user = $this->userRepository->findOneBy(['id' => $id], ['password' => 'NONE']);