Getting Started

Minimal Setup

Install the Bundle
```
composer require dbp/relay-core-connector-ldap-bundle
```
Ensure digital-blueprint/relay-core is also installed (dependency).

Enable the Bundle Add to config/bundles.php:

return [
    // ...
    DigitalBlueprint\RelayCoreConnectorLdapBundle\DbpRelayCoreConnectorLdapBundle::class => ['all' => true],
];

Configure LDAP Connection Publish the default config:

php bin/console dbp:ldap:install

Edit config/packages/dbp_relay_core_connector_ldap.yaml:

dbp_relay_core_connector_ldap:
    host: 'ldap.example.com'
    port: 389
    base_dn: 'dc=example,dc=com'
    username: 'cn=admin,dc=example,dc=com'
    password: 'admin_password'
    search_attribute: 'uid'

First Use Case: LDAP User Lookup Inject the AuthorizationDataProviderInterface into a service:

use DigitalBlueprint\RelayCore\Authorization\AuthorizationDataProviderInterface;

class MyService {
    public function __construct(
        private AuthorizationDataProviderInterface $ldapProvider
    ) {}

    public function fetchUserRoles(string $username): array {
        $userData = $this->ldapProvider->getUserData($username);
        return $userData['roles'] ?? [];
    }
}

Implementation Patterns

Core Workflows

User Authentication Integration Use the bundle with Symfony’s security component:

# config/packages/security.yaml
security:
    providers:
        ldap_provider:
            id: dbp_relay_core_connector_ldap.ldap_user_provider

Role-Based Access Control (RBAC) Map LDAP groups to Symfony roles in config/packages/security.yaml:
```
access_control:
    - { path: ^/admin, roles: ROLE_ADMIN }
```
Ensure LDAP groups are synced to Symfony roles via the provider’s loadUserByUsername().

Custom Attribute Mapping Override the default attribute mapping in a custom service:

// src/Service/CustomLdapMapper.php
use DigitalBlueprint\RelayCoreConnectorLdapBundle\Mapper\LdapAttributeMapperInterface;

class CustomLdapMapper implements LdapAttributeMapperInterface {
    public function mapAttributes(array $ldapEntry): array {
        return [
            'username' => $ldapEntry['uid'][0] ?? null,
            'email' => $ldapEntry['mail'][0] ?? null,
            'roles' => ['ROLE_CUSTOM_' . strtoupper($ldapEntry['department'][0])],
        ];
    }
}

services:
    DigitalBlueprint\RelayCoreConnectorLdapBundle\Mapper\LdapAttributeMapperInterface: '@App\Service\CustomLdapMapper'

Caching LDAP Responses Cache user data to reduce LDAP queries:

# config/packages/framework.yaml
framework:
    cache:
        app: cache.adapter.redis

Configure the provider to use cache:

dbp_relay_core_connector_ldap:
    cache_enabled: true
    cache_ttl: 3600

Integration Tips

Symfony Flex Recipes: Use php bin/console make:ldap-provider (if a recipe exists; check the docs).
Environment-Specific Config: Use %env() for sensitive data:
```
password: '%env(LDAP_ADMIN_PASSWORD)%'
```

Testing: Mock the AuthorizationDataProviderInterface in PHPUnit:

$this->createMock(AuthorizationDataProviderInterface::class)
     ->method('getUserData')
     ->willReturn(['roles' => ['ROLE_TEST']]);

Gotchas and Tips

Pitfalls

Connection Timeouts

LDAP timeouts may cause silent failures. Log errors explicitly:

try {
    $this->ldapProvider->getUserData($username);
} catch (\Exception $e) {
    // Log with stack trace
    throw new \RuntimeException('LDAP lookup failed', 0, $e);
}

Configure timeout in dbp_relay_core_connector_ldap.yaml:
```
timeout: 5.0  # seconds
```

Case Sensitivity in Usernames
- LDAP searches are case-insensitive by default, but some providers (e.g., Active Directory) may vary. Normalize usernames:
```
$username = strtolower($username);
```
Group Membership Caching
- Group membership queries can be expensive. Cache results aggressively:
```
dbp_relay_core_connector_ldap:
    cache_groups: true
```
Schema Differences
- Not all LDAP servers use uid for usernames. Adjust search_attribute:
```
search_attribute: 'sAMAccountName'  # For Active Directory
```

Debugging

Enable LDAP Debugging Add to config/packages/monolog.yaml:

handlers:
    ldap:
        type: stream
        path: "%kernel.logs_dir%/ldap.log"
        level: debug
        channels: ["ldap"]

Enable debug mode in the bundle config:

dbp_relay_core_connector_ldap:
    debug: true

Validate LDAP Connection Use the dbp:ldap:test-connection command:
```
php bin/console dbp:ldap:test-connection
```

Extension Points

Custom User Provider Extend the default provider to add logic:

class CustomLdapUserProvider extends \DigitalBlueprint\RelayCoreConnectorLdapBundle\Security\LdapUserProvider {
    public function refreshUser(UserInterface $user) {
        // Custom refresh logic
        return parent::refreshUser($user);
    }
}

Override in services.yaml:

services:
    DigitalBlueprint\RelayCoreConnectorLdapBundle\Security\LdapUserProvider: '@App\Security\CustomLdapUserProvider'

Event Listeners Listen for LDAP events (e.g., ldap.user.loaded):

use Symfony\Component\EventDispatcher\GenericEvent;

class LdapUserListener {
    public function onUserLoaded(GenericEvent $event) {
        $userData = $event->getSubject();
        // Modify user data before Symfony processes it
    }
}

services:
    App\EventListener\LdapUserListener:
        tags:
            - { name: kernel.event_listener, event: ldap.user.loaded, method: onUserLoaded }

Dynamic Configuration Load LDAP config from a database or API:

// src/DependencyInjection/Compiler/LdapConfigPass.php
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class LdapConfigPass implements CompilerPassInterface {
    public function process(ContainerBuilder $container) {
        $ldapConfig = $this->fetchConfigFromDatabase();
        $container->setParameter('dbp_relay_core_connector_ldap.config', $ldapConfig);
    }
}

services:
    App\DependencyInjection\Compiler\LdapConfigPass:
        tags: [{ name: compiler.pass }]

Relay Core Connector Ldap Bundle Laravel Package