Ldap Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require connectholland/ldap-bundle in your Laravel project (note: this bundle is Symfony-based, so ensure compatibility with Laravel via Symfony bridge or use in a Symfony project).

2. Bundle Registration Add the bundle to config/app.php under providers:

   'providers' => [
       // ...
       ConnectHolland\LdapBundle\ConnectHollandLdapBundle::class,
   ],
   

3. Basic Configuration Configure config/security.php (or app/config/security.yml if using Symfony):

   security:
       providers:
           my_ldap:
               connect_holland_ldap:
                   connection:
                       host: 'ldap.example.com'
                       port: 389
                       encryption: 'none' # or 'ssl', 'tls'
                   user_factory:
                       type: doctrine
                       user_class: 'App\User' # Laravel's Eloquent model
                       username_column: 'email' # Column to map LDAP username to
                       user_property_map:
                           firstName: 'givenName'
                           lastName: 'sn'
                           email: 'mail'
   

4. First Use Case Authenticate a user via LDAP:

   use ConnectHolland\LdapBundle\Security\LdapUserProvider;
   
   // In a controller or service
   $ldapProvider = app(LdapUserProvider::class);
   $user = $ldapProvider->loadUserByUsername('ldap_username');
   

Implementation Patterns

Workflows

1. LDAP Authentication with Existing Users

   • Use the doctrine or sulu user factory to sync LDAP users with your database.
   • Example: Auto-create a user in Laravel if they don’t exist in the DB but are valid in LDAP.

     // In a custom user factory service
     public function loadUserByUsername($username)
     {
         $ldapUser = $this->ldap->findUser($username);
         if (!$ldapUser) return null;
     
         $user = User::where('email', $ldapUser->getEmail())->first();
         if (!$user) {
             $user = User::create([
                 'email' => $ldapUser->getEmail(),
                 'first_name' => $ldapUser->getFirstName(),
                 // ...
             ]);
         }
         return $user;
     }
     

2. Role Mapping

   • Map LDAP group memberships to Laravel roles (e.g., using spatie/laravel-permission):

     user_factory:
         role_map:
             'cn=admins,ou=groups': 'admin'
             'cn=users,ou=groups': 'user'
     

3. Fallback Authentication

   • Combine LDAP with database auth in security.php:

     firewalls:
         main:
             provider: [my_ldap, my_database]
     

Integration Tips

• Laravel-Specific Adjustments: Replace Symfony’s UserInterface with Laravel’s Illuminate\Contracts\Auth\Authenticatable. Extend the bundle’s UserFactory to work with Laravel’s Eloquent:

  use Illuminate\Database\Eloquent\Model;
  
  class LaravelUserFactory extends DoctrineUserFactory
  {
      protected function createUser(array $data)
      {
          return Model::create($data);
      }
  }
  

• Caching: Cache LDAP queries to reduce load (e.g., using Laravel’s cache):

  $ldapUser = Cache::remember("ldap_user_{$username}", now()->addHours(1), function() use ($username) {
      return $this->ldap->findUser($username);
  });
  

• Testing: Use Laravel’s Mockery to simulate LDAP responses in tests:

  $mockLdap = Mockery::mock('overload:ConnectHolland\LdapBundle\Ldap\Connection');
  $mockLdap->shouldReceive('bind')->andReturn(true);
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony Components:

   • The bundle relies on Symfony’s LDAP component (v3.x), which may conflict with Laravel’s Symfony bridge. Ensure compatibility or fork the bundle for Laravel 8/9.
   • Fix: Use a wrapper like digitalbush/laravel-ldap or update the bundle’s dependencies.

2. User Factory Limitations:

   • The doctrine factory assumes Doctrine ORM. For Laravel, override the factory or use a custom service.
   • Fix: Register a custom factory in config/services.php:

     'ldap.user_factory' => App\Services\LaravelUserFactory::class,
     

3. LDAP Schema Mismatches:

   • LDAP attributes (e.g., uid vs. sAMAccountName) may not align with your Laravel model.
   • Fix: Adjust user_property_map in config or pre-process LDAP data:

     $ldapUser->setUsername($ldapUser->getAttribute('sAMAccountName'));
     

4. Archived Status:

   • No active maintenance; expect bugs in newer Laravel/Symfony versions.
   • Fix: Fork the repo and update dependencies (e.g., Symfony LDAP to v5+).

Debugging

• Enable LDAP Logging: Add to config/logging.php:

  'channels' => [
      'ldap' => [
          'driver' => 'single',
          'path' => storage_path('logs/ldap.log'),
          'level' => 'debug',
      ],
  ],
  

  Then log LDAP operations:

  \Log::channel('ldap')->debug('LDAP Query', ['data' => $ldapUser->getAttributes()]);
  

• Common Errors:

  • "Connection refused": Verify LDAP server host/port and firewall rules.
  • "Invalid credentials": Check bind DN/password in connection config.
  • "Class not found": Ensure user_class in config matches your Laravel model namespace.

Extension Points

1. Custom User Factories: Create a service to extend functionality:

   class CustomUserFactory extends AbstractUserFactory
   {
       public function loadUserByUsername($username)
       {
           // Custom logic (e.g., multi-domain LDAP)
           return parent::loadUserByUsername($username);
       }
   }
   

   Register it in config/services.php:

   'ldap.user_factory' => App\Services\CustomUserFactory::class,
   

2. Event Listeners: Listen for LDAP events (e.g., user sync) using Laravel’s events:

   Event::listen('ldap.user.synced', function ($user) {
       // Trigger post-sync actions (e.g., send welcome email)
   });
   

3. Laravel Auth Integration: Override Laravel’s AuthManager to prioritize LDAP:

   use ConnectHolland\LdapBundle\Security\LdapUserProvider;
   
   protected function createUserProvider()
   {
       return new LdapUserProvider($this->app['config']['ldap']);
   }