Authenticating against an LDAP server

3.3 version
Maintained Unmaintained

Authenticating against an LDAP server

Symfony provides different means to work with an LDAP server.

The Security component offers:

  • The ldap user provider, using the LdapUserProvider class. Like all other user providers, it can be used with any authentication provider.
  • The form_login_ldap authentication provider, for authenticating against an LDAP server using a login form. Like all other authentication providers, it can be used with any user provider.
  • The http_basic_ldap authentication provider, for authenticating against an LDAP server using HTTP Basic. Like all other authentication providers, it can be used with any user provider.

This means that the following scenarios will work:

  • Checking a user's password and fetching user information against an LDAP server. This can be done using both the LDAP user provider and either the LDAP form login or LDAP HTTP Basic authentication providers.
  • Checking a user's password against an LDAP server while fetching user information from another source (database using FOSUserBundle, for example).
  • Loading user information from an LDAP server, while using another authentication strategy (token-based pre-authentication, for example).

Ldap Configuration Reference

See SecurityBundle Configuration ("security") for the full LDAP configuration reference (form_login_ldap, http_basic_ldap, ldap). Some of the more interesting options are explained below.

Configuring the LDAP client

All mechanisms actually need an LDAP client previously configured. The providers are configured to use a default service named ldap, but you can override this setting in the security component's configuration.

An LDAP client can be simply configured using the built-in LDAP PHP extension with the following service definition:

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    # app/config/services.yml
    services:
        Symfony\Component\Ldap\Ldap:
            arguments: ['@Symfony\Component\Ldap\Adapter\ExtLdap\Adapter']
        Symfony\Component\Ldap\Adapter\ExtLdap\Adapter:
            arguments:
                -   host: my-server
                    port: 389
                    encryption: tls
                    options:
                        protocol_version: 3
                        referrals: false
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    <!-- app/config/services.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
    
        <services>
            <service id="Symfony\Component\Ldap\Ldap">
                <argument type="service" id="Symfony\Component\Ldap\Adapter\ExtLdap\Adapter" />
            </service>
            <service id="Symfony\Component\Ldap\Adapter\ExtLdap\Adapter">
                <argument type="collection">
                    <argument key="host">my-server</argument>
                    <argument key="port">389</argument>
                    <argument key="encryption">tls</argument>
                    <argument key="options" type="collection">
                        <argument key="protocol_version">3</argument>
                        <argument key="referrals">false</argument>
                    </argument>
                </argument>
            </service>
        </services>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    // app/config/services.php
    use Symfony\Component\Ldap\Ldap;
    use Symfony\Component\Ldap\Adapter\ExtLdap\Adapter;
    use Symfony\Component\DependencyInjection\Definition;
    
    $container->register(Ldap::class)
        ->addArgument(new Reference(Adapter::class);
    
    $container
        ->register(Adapter::class)
        ->setArguments(array(
            'host' => 'my-server',
            'port' => 389,
            'encryption' => 'tls',
            'options' => array(
                'protocol_version' => 3,
                'referrals' => false
            ),
        ));
    

Fetching Users Using the LDAP User Provider

If you want to fetch user information from an LDAP server, you may want to use the ldap user provider.

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    # app/config/security.yml
    security:
        # ...
    
        providers:
            my_ldap:
                ldap:
                    service: Symfony\Component\Ldap\Ldap
                    base_dn: dc=example,dc=com
                    search_dn: "cn=read-only-admin,dc=example,dc=com"
                    search_password: password
                    default_roles: ROLE_USER
                    uid_key: uid
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    <!-- app/config/security.xml -->
    <?xml version="1.0" encoding="UTF-8"?>
    <srv:container xmlns="http://symfony.com/schema/dic/security"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:srv="http://symfony.com/schema/dic/services"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd">
    
        <config>
            <provider name="my_ldap">
                <ldap
                        service="Symfony\Component\Ldap\Ldap"
                        base-dn="dc=example,dc=com"
                        search-dn="cn=read-only-admin,dc=example,dc=com"
                        search-password="password"
                        default-roles="ROLE_USER"
                        uid-key="uid"
                />
            </provider>
        </config>
    </srv:container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    use Symfony\Component\Ldap\Ldap;
    
    $container->loadFromExtension('security', array(
        'providers' => array(
            'ldap_users' => array(
                'ldap' => array(
                    'service' => Ldap::class,
                    'base_dn' => 'dc=example,dc=com',
                    'search_dn' => 'cn=read-only-admin,dc=example,dc=com',
                    'search_password' => 'password',
                    'default_roles' => 'ROLE_USER',
                    'uid_key' => 'uid',
                ),
            ),
        ),
    );
    

Caution

The Security component escapes provided input data when the LDAP user provider is used. However, the LDAP component itself does not provide any escaping yet. Thus, it's your responsibility to prevent LDAP injection attacks when using the component directly.

The ldap user provider supports many different configuration options:

service

type: string default: ldap

This is the name of your configured LDAP client. You can freely chose 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 in order 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 in order 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.

uid_key

type: string default: sAMAccountName

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

  • sAMAccountName
  • userPrincipalName
  • uid

filter

type: string default: ({uid_key}={username})

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 {username} string will be replaced by the username 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).

Of course, the username will be escaped, in order to prevent LDAP injection.

The syntax for the filter key is defined by RFC4515.

Authenticating against an LDAP server

Authenticating against an LDAP server can be done using either the form login or the HTTP Basic authentication providers.

They are configured exactly as their non-LDAP counterparts, with the addition of two configuration keys and one optional key:

service

type: string default: ldap

This is the name of your configured LDAP client. You can freely chose 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: {username}

This key defines the form of the string used in order to compose the DN of the user, from the username. The {username} 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={username},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="{username}"). The placeholder value will be replaced by the actual username.

When this option is used, dn_string has to be updated accordingly. 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. If the query_string option is uid="{username}", then the authentication provider can authenticate users from both DN.

Bear in mind 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.

Configuration example for form login

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    # app/config/security.yml
    security:
        # ...
    
        firewalls:
            main:
                # ...
                form_login_ldap:
                    # ...
                    service: Symfony\Component\Ldap\Ldap;
                    dn_string: 'uid={username},dc=example,dc=com'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    <!-- app/config/security.xml -->
    <?xml version="1.0" encoding="UTF-8"?>
    <srv:container xmlns="http://symfony.com/schema/dic/security"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:srv="http://symfony.com/schema/dic/services"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd">
    
        <config>
            <firewall name="main">
                <form-login-ldap
                        service="Symfony\Component\Ldap\Ldap"
                        dn-string="uid={username},dc=example,dc=com" />
            </firewall>
        </config>
    </srv:container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    use Symfony\Component\Ldap\Ldap;
    
    $container->loadFromExtension('security', array(
        'firewalls' => array(
            'main' => array(
                'form_login_ldap' => array(
                    'service' => Ldap::class,
                    'dn_string' => 'uid={username},dc=example,dc=com',
                    // ...
                ),
            ),
        )
    );
    

Configuration example for HTTP Basic

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    # app/config/security.yml
    security:
        # ...
    
        firewalls:
            main:
                # ...
                http_basic_ldap:
                    # ...
                    service: Symfony\Component\Ldap\Ldap
                    dn_string: 'uid={username},dc=example,dc=com'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    <!-- app/config/security.xml -->
    <?xml version="1.0" encoding="UTF-8"?>
    <srv:container xmlns="http://symfony.com/schema/dic/security"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:srv="http://symfony.com/schema/dic/services"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd">
    
        <config>
            <firewall name="main" stateless="true">
                <http-basic-ldap service="Symfony\Component\Ldap\Ldap" dn-string="uid={username},dc=example,dc=com" />
            </firewall>
        </config>
    </srv:container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    use Symfony\Component\Ldap\Ldap;
    
    $container->loadFromExtension('security', array(
        'firewalls' => array(
            'main' => array(
                'http_basic_ldap' => array(
                    'service' => Ldap::class,
                    'dn_string' => 'uid={username},dc=example,dc=com',
                    // ...
                ),
                'stateless' => true,
            ),
        ),
    );
    

Configuration example for form login and query_string

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    # app/config/security.yml
    security:
        # ...
    
        firewalls:
            main:
                # ...
                form_login_ldap:
                    # ...
                    service: Symfony\Component\Ldap\Ldap
                    dn_string: 'dc=example,dc=com'
                    query_string: '(&(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    <!-- app/config/security.xml -->
    <?xml version="1.0" encoding="UTF-8"?>
    <srv:container xmlns="http://symfony.com/schema/dic/security"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:srv="http://symfony.com/schema/dic/services"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd">
    
        <config>
            <firewall name="main">
                <form-login-ldap
                        service="Symfony\Component\Ldap\Ldap"
                        dn-string="dc=example,dc=com"
                        query-string="(&amp;(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))" />
            </firewall>
        </config>
    </srv:container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    // app/config/security.php
    use Symfony\Component\Ldap\Ldap;
    
    $container->loadFromExtension('security', array(
        'firewalls' => array(
            'main' => array(
                'form_login_ldap' => array(
                    'service' => Ldap::class,
                    'dn_string' => 'dc=example,dc=com',
                    'query_string' => '(&(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))',
                    // ...
                ),
            ),
        )
    );
    

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.