Password Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cyve/password-manager-bundle
   

   Enable the bundle in config/bundles.php:

   Cyve\PasswordManagerBundle\CyvePasswordManagerBundle::class => ['all' => true],
   

2. Routing & Security Add the routes in config/routes.yaml:

   cyve_password_manager:
       resource: "@CyvePasswordManagerBundle/Resources/config/routing.yaml"
   

   Configure security.yaml to enable login links:

   security:
       firewalls:
           main:
               login_link:
                   check_route: app_login_check
                   signature_properties: ['userIdentifier']
   

3. First Use Case

   • Trigger a password reset by visiting /password/request-login-link (user submits email/username).
   • User receives an email with a login link (redirects to /password/update).
   • User logs in via the link and updates their password.

Implementation Patterns

Workflow: Password Recovery

1. Request Login Link

   • User submits identifier (email/username) via /password/request-login-link.
   • Bundle validates user existence and sends a signed login link via email (using Symfony’s LoginLinkAuthenticator).
   • Link includes _target_path=/password/update (default).

2. Password Update

   • User clicks the link → redirected to /password/update (protected route).
   • Form submits new password → bundle updates it via UserPasswordHasher.

3. CLI Reset (Admin Use)

   bin/console cyve:password:reset <username> <new_password>
   

   • Useful for bulk resets or emergency access.

Integration Tips

• Customize Emails Override the email template in templates/CyvePasswordManagerBundle/email/login_link.html.twig.
• Extend User Model Ensure your User entity implements PasswordAuthenticatedUserInterface (Symfony’s requirement for password updates).
• Route Customization Override routing.yaml to change /password/update or /request-login-link paths.
• Security Firewall Ensure login_link is configured in the firewall where the user should authenticate.

Example: Customizing the Update Form

Extend the controller or template:

{# templates/CyvePasswordManagerBundle/password/update.html.twig #}
{{ form_start(form, { attr: { class: 'custom-form' } }) }}
    {{ form_widget(form) }}
    <button type="submit" class="btn btn-primary">Update Password</button>
{{ form_end(form) }}

Gotchas and Tips

Pitfalls

1. _target_path Hardcoding

   • The bundle assumes _target_path=/password/update. If you rename this in security.yaml, redirection breaks.
   • Fix: Use the default or update the bundle’s LoginLinkAuthenticator to match your config.

2. Missing UserPasswordHasher

   • If your User entity lacks PasswordAuthenticatedUserInterface, password updates fail silently.
   • Fix: Add the interface and ensure password property is protected.

3. Email Configuration

   • The bundle relies on Symfony’s mailer. If emails aren’t sent, check:
     • MAILER_DSN in .env.
     • Twig template paths (templates/CyvePasswordManagerBundle/email/).

4. CSRF Protection

   • The /password/update route is protected but may lack CSRF for POST requests.
   • Fix: Ensure security.yaml includes csrf_token for the form.

Debugging Tips

• Check Login Links Use bin/console debug:container cyve_password_manager.login_link_authenticator to verify the authenticator is registered.
• Validate Emails Test with a real SMTP server (e.g., Mailtrap) to debug email delivery.
• Log Events Enable Symfony’s event dispatcher logs to trace password update/reset flows:

  # config/services.yaml
  Symfony\Component\EventDispatcher\Debug\TraceableEventDispatcher:
      decorates: event_dispatcher
      arguments: ['@.inner']
  

Extension Points

1. Custom Authenticator Extend LoginLinkAuthenticator to add logic (e.g., rate-limiting):

   class CustomLoginLinkAuthenticator extends LoginLinkAuthenticator
   {
       public function checkPostCredentials($credentials): void
       {
           // Add custom validation
       }
   }
   

   Register it in security.yaml:

   firewalls:
       main:
           login_link:
               authenticator: app.custom_login_link
   

2. Password Policies Add validation to the update form (e.g., minimum length):

   // src/EventListener/PasswordUpdateListener.php
   use Symfony\Component\Form\FormEvent;
   use Symfony\Component\Form\FormEvents;
   
   class PasswordUpdateListener
   {
       public function __construct()
       {
           $this->container->get('event_dispatcher')->addListener(
               FormEvents::PRE_SUBMIT,
               [$this, 'onPasswordUpdate']
           );
       }
   
       public function onPasswordUpdate(FormEvent $event)
       {
           $data = $event->getData();
           if (strlen($data['plainPassword']) < 8) {
               $event->getForm()->addError(new FormError('Password too short.'));
           }
       }
   }
   

3. Multi-Factor Auth (MFA) Integrate with Symfony’s MfaAuthenticatorInterface to require MFA during password updates.

Configuration Quirks

• Signature Properties The signature_properties in security.yaml must match your User entity’s identifier (e.g., email or username). Example for email:

  signature_properties: ['email']
  

• Route Overrides If you override routes, ensure the new paths are reflected in:
  • Email templates (login link URLs).
  • CSRF tokens (if using custom forms).