LDAP

Batch Updating

Use the entry manager's applyOperations() method to update multiple attributes at once:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

use Symfony\Component\Ldap\Adapter\ExtLdap\UpdateOperation;
use Symfony\Component\Ldap\Entry;
use Symfony\Component\Ldap\Ldap;
// ...

$entry = new Entry('cn=Fabien Potencier,dc=symfony,dc=com', [
    'sn' => ['fabpot'],
    'objectClass' => ['inetOrgPerson'],
]);

$entryManager = $ldap->getEntryManager();

// adding multiple email addresses at once
$entryManager->applyOperations($entry->getDn(), [
    new UpdateOperation(LDAP_MODIFY_BATCH_ADD, 'mail', 'new1@example.com'),
    new UpdateOperation(LDAP_MODIFY_BATCH_ADD, 'mail', 'new2@example.com'),
]);

Possible operation types are LDAP_MODIFY_BATCH_ADD, LDAP_MODIFY_BATCH_REMOVE, LDAP_MODIFY_BATCH_REMOVE_ALL, LDAP_MODIFY_BATCH_REPLACE. Parameter $values must be NULL when using LDAP_MODIFY_BATCH_REMOVE_ALL operation type.

service

type: string default: ldap

This is the name of your configured LDAP client. You can freely choose the name, but it must be unique in your application and it cannot start with a number or contain white spaces.

base_dn

type: string default: null

This is the base DN for the directory

search_dn

type: string default: null

This is your read-only user's DN, which will be used to authenticate against the LDAP server to fetch the user's information.

search_password

type: string default: null

This is your read-only user's password, which will be used to authenticate against the LDAP server to fetch the user's information.

default_roles

type: array default: []

This is the default role you wish to give to a user fetched from the LDAP server. If you do not configure this key, your users won't have any roles, and will not be considered as authenticated fully.

role_fetcher

Type: string Default: null

When your LDAP service provides user roles, this option allows you to define the service that retrieves these roles. The role fetcher service must implement the Symfony\Component\Ldap\Security\RoleFetcherInterface. When this option is set, the default_roles option is ignored.

Symfony provides Symfony\Component\Ldap\Security\MemberOfRoles, a concrete implementation of the interface that fetches roles from the ismemberof attribute (configurable via its $attributeName constructor argument). See Using MemberOfRoles below for an example.

uid_key

type: string default: null

This is the entry's key to use as its UID. Depends on your LDAP server implementation. Commonly used values are:

• sAMAccountName (default)
• userPrincipalName
• uid

If you pass null as the value of this option, the default UID key sAMAccountName is used.

extra_fields

type: array default: null

Defines the custom fields to pull from the LDAP server. If any field does not exist, an \InvalidArgumentException will be thrown.

filter

type: string default: null

This key lets you configure which LDAP query will be used. The {uid_key} string will be replaced by the value of the uid_key configuration value (by default, sAMAccountName), and the {user_identifier} string will be replaced by the user identifier you are trying to load.

For example, with a uid_key of uid, and if you are trying to load the user fabpot, the final string will be: (uid=fabpot).

If you pass null as the value of this option, the default filter is used ({uid_key}={user_identifier}).

To prevent LDAP injection, the username will be escaped.

The syntax for the filter key is defined by RFC4515.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# config/services.yaml
services:
    Symfony\Component\Ldap\Security\MemberOfRoles:
        arguments:
            $mapping:
                admins: 'ROLE_ADMIN'
                users: 'ROLE_USER'

# config/packages/security.yaml
security:
    providers:
        my_ldap:
            ldap:
                service: Symfony\Component\Ldap\Ldap
                base_dn: dc=example,dc=com
                uid_key: uid
                extra_fields: ['ismemberof']
                role_fetcher: Symfony\Component\Ldap\Security\MemberOfRoles

1
2
3
4
5
6
7
8
9
10
11
12
13

// config/services.php
use Symfony\Component\Ldap\Security\MemberOfRoles;

return function (ContainerConfigurator $container): void {
    $container->services()
        ->set(MemberOfRoles::class)
            ->args([
                '$mapping' => [
                    'admins' => 'ROLE_ADMIN',
                    'users' => 'ROLE_USER',
                ],
            ]);
};

service

type: string default: ldap

This is the name of your configured LDAP client. You can freely choose the name, but it must be unique in your application and it cannot start with a number or contain white spaces.

dn_string

type: string default: {user_identifier}

This key defines the form of the string used to compose the DN of the user, from the username. The {user_identifier} string is replaced by the actual username of the person trying to authenticate.

For example, if your users have DN strings in the form uid=einstein,dc=example,dc=com, then the dn_string will be uid={user_identifier},dc=example,dc=com.

query_string

type: string default: null

This (optional) key makes the user provider search for a user and then use the found DN for the bind process. This is useful when using multiple LDAP user providers with different base_dn. The value of this option must be a valid search string (e.g. uid="{user_identifier}"). The placeholder value will be replaced by the actual user identifier.

When this option is used, query_string will search in the DN specified by dn_string and the DN resulted of the query_string will be used to authenticate the user with their password. Following the previous example, if your users have the following two DN: dc=companyA,dc=example,dc=com and dc=companyB,dc=example,dc=com, then dn_string should be dc=example,dc=com.

Note that usernames must be unique across both DN, as the authentication provider won't be able to select the correct user for the bind process if more than one is found.

Examples are provided below, for both form_login_ldap and http_basic_ldap. The json_login_ldap provider is configured in the same way (see the LDAP configuration reference).

Configuration example for form login

1
2
3
4
5
6
7
8
9
10
11

# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            form_login_ldap:
                # ...
                service: Symfony\Component\Ldap\Ldap
                dn_string: 'uid={user_identifier},dc=example,dc=com'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\Ldap\Ldap;

return App::config([
    'security' => [
        // ...
        'firewalls' => [
            'main' => [
                'form_login_ldap' => [
                    'service' => Ldap::class,
                    'dn_string' => 'uid={user_identifier},dc=example,dc=com',
                ],
            ],
        ],
    ],
]);

Configuration example for HTTP Basic

1
2
3
4
5
6
7
8
9
10

# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            stateless: true
            http_basic_ldap:
                service: Symfony\Component\Ldap\Ldap
                dn_string: 'uid={user_identifier},dc=example,dc=com'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\Ldap\Ldap;

return App::config([
    'security' => [
        // ...
        'firewalls' => [
            'main' => [
                'stateless' => true,
                'http_basic_ldap' => [
                    'service' => Ldap::class,
                    'dn_string' => 'uid={user_identifier},dc=example,dc=com',
                ],
            ],
        ],
    ],
]);

Configuration example for form login and query_string

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            form_login_ldap:
                service: Symfony\Component\Ldap\Ldap
                dn_string: 'dc=example,dc=com'
                query_string: '(&(uid={user_identifier})(memberOf=cn=users,ou=Services,dc=example,dc=com))'
                search_dn: '...'
                search_password: 'the-raw-password'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\Ldap\Ldap;

return App::config([
    'security' => [
        // ...
        'firewalls' => [
            'main' => [
                'form_login_ldap' => [
                    'service' => Ldap::class,
                    'dn_string' => 'dc=example,dc=com',
                    'query_string' => '(&(uid={user_identifier})(memberOf=cn=users,ou=Services,dc=example,dc=com))',
                    'search_dn' => '...',
                    'search_password' => 'the-raw-password',
                ],
            ],
        ],
    ],
]);