Directory Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cisco-systems/directory-bundle:dev-master
   

   Add to AppKernel.php:

   new CiscoSystems\DirectoryBundle\CiscoSystemsDirectoryBundle(),
   

2. Basic Configuration (config.yml):

   cisco_systems_directory:
       default_directory: main
       directories:
           main:
               servers:
                   primary:
                       host: ads1.example.com
   

3. First Use Case: Inject the DirectoryManager service to query AD:

   use CiscoSystems\DirectoryBundle\Manager\DirectoryManager;
   
   class MyController extends Controller
   {
       public function __construct(DirectoryManager $directoryManager)
       {
           $this->directoryManager = $directoryManager;
       }
   
       public function searchUsers()
       {
           $users = $this->directoryManager->getDirectory('main')->search('(objectClass=user)');
           return $this->render('users.html.twig', ['users' => $users]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Directory Configuration:

   • Define multiple AD servers under directories.<name>.servers.
   • Use default_directory to set a fallback.
   • Override default RDN/password via default_rdn/default_password.

2. Querying AD:

   • Use DirectoryManager to fetch a directory instance:

     $directory = $this->directoryManager->getDirectory('main');
     

   • Execute LDAP searches:

     $results = $directory->search('(sn=Doe)');
     $entry = $directory->findEntry('uid=jdoe');
     

3. Custom Repositories:

   • Extend CiscoSystems\DirectoryBundle\Repository\DirectoryRepository for domain-specific logic.
   • Bind via repository in config:

     directories:
         main:
             repository: 'AppBundle\Repository\CustomDirectoryRepository'
     

4. Service Integration:

   • Bind DirectoryManager to controllers/services for reusable AD access.
   • Example: Authenticate users via AD:

     $user = $directory->findEntry('uid=' . $username);
     if ($user && $directory->bind($user->getDn(), $password)) {
         // Authenticated
     }
     

5. Caching:

   • Cache frequent queries using Symfony’s cache system:

     $cache = $this->get('cache.app');
     $key = 'ad_users_' . md5($searchFilter);
     $users = $cache->get($key, function() use ($directory, $searchFilter) {
         return $directory->search($searchFilter);
     });
     

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • Last release in 2016; verify compatibility with modern PHP/LDAP extensions.
   • May require patches for PHP 7.4+/8.x or Symfony 4.4+.

2. LDAP Extension:

   • Ensure php-ldap is installed and enabled (php -m | grep ldap).
   • Configure ldap in php.ini:

     extension=ldap
     ldap.max_links = -1
     

3. Configuration Overrides:

   • Parameters like %myAppsLdapUsername% must be defined in parameters.yml or resolved via dependency injection.

4. Connection Failures:

   • Handle CiscoSystems\DirectoryBundle\Exception\DirectoryException for network/AD issues:

     try {
         $directory->search('...');
     } catch (DirectoryException $e) {
         $this->addFlash('error', 'AD unavailable: ' . $e->getMessage());
     }
     

5. Performance:

   • Avoid fetching entire directories; use filters (e.g., (objectClass=user)).
   • Limit results with ->setLimit(100).

Debugging Tips

1. Enable LDAP Logging: Add to php.ini:

   ldap.trace_level = 32767
   

   Check logs for connection/query details.

2. Test Connections: Use a standalone script to validate AD access:

   $ldap = ldap_connect('ads1.example.com');
   ldap_bind($ldap, 'username', 'password');
   

3. Common Errors:

   • "Unable to connect": Verify host, firewall rules, and AD server status.
   • "Invalid credentials": Double-check default_rdn/default_password in config.
   • "No such object": Validate DN syntax (e.g., uid=jdoe,ou=users,dc=example,dc=com).

Extension Points

1. Custom Entries: Extend CiscoSystems\DirectoryBundle\Model\EntryInterface for project-specific attributes.

2. Event Listeners: Subscribe to directory.search events (if the bundle supports them) to log/transform results:

   services:
       app.ad_listener:
           class: AppBundle\EventListener\DirectoryListener
           tags:
               - { name: kernel.event_listener, event: directory.search, method: onSearch }
   

3. Fallback Servers: Implement retry logic for secondary servers in config:

   if (!$primary->search($filter)) {
       $secondary->search($filter);
   }
   

4. Symfony Forms: Use the bundle with Symfony\Component\Form\Extension\Core\Type\ChoiceType for AD-based dropdowns:

   $users = $directory->search('(objectClass=user)');
   $userChoices = array_map(function($entry) {
       return $entry->getAttribute('cn');
   }, $users);