feature #7420 Added query_string LDAP config option (nietonfir, javiereguiluz, lsmith77)

This PR was merged into the master branch.

Discussion
----------

Added query_string LDAP config option

docs for symfony/symfony#21402

Commits
-------

b82cafd clean up
446ba38 added query_string LDAP config option
ed58da8 Minor reword
f133269 Explain the query_string ldap authentication provider configuration key

Author: xabbuh

reference/configuration/security.rst

@@ -142,9 +142,10 @@ Each part will be explained in the next section.
                     http_basic:
                         provider: some_key_from_above
                     http_basic_ldap:
-                        provider:  some_key_from_above
-                        service:   ldap
-                        dn_string: '{username}'
+                        provider:     some_key_from_above
+                        service:      ldap
+                        dn_string:    '{username}'
+                        query_string: ~
                     http_digest:
                         provider: some_key_from_above
                     guard:
@@ -237,8 +238,9 @@ Each part will be explained in the next section.
                         # new in Symfony 2.3
                         require_previous_session: true
 
-                        service:   ~
-                        dn_string: '{username}'
+                        service:      ~
+                        dn_string:    '{username}'
+                        query_string: ~
 
                     remember_me:
                         token_provider: name
@@ -446,6 +448,17 @@ placeholder will be replaced with the user-provided value (his login).
 Depending on your LDAP server's configuration, you may need to override
 this value.
 
+query_string
+............
+
+**type**: ``string`` **default**: ``null``
+
+This is the string which will be used to query for the DN. The ``{username}``
+placeholder will be replaced with the user-provided value (their login).
+Depending on your LDAP server's configuration, you will need to override
+this value. This setting is only necessary if the user's DN cannot be derived
+statically using the ``dn_string`` config option.
+
 User provider
 ~~~~~~~~~~~~~
 

security/ldap.rst

@@ -246,7 +246,7 @@ 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:
+addition of two configuration keys and one optional key:
 
 service
 .......
@@ -270,6 +270,28 @@ 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``.
 
@@ -288,8 +310,6 @@ Configuration example for form login
                 main:
                     # ...
                     form_login_ldap:
-                        login_path: login
-                        check_path: login_check
                         # ...
                         service: ldap
                         dn_string: 'uid={username},dc=example,dc=com'
@@ -307,8 +327,6 @@ Configuration example for form login
             <config>
                 <firewall name="main">
                     <form-login-ldap
-                            login-path="login"
-                            check-path="login_check"
                             service="ldap"
                             dn-string="uid={username},dc=example,dc=com" />
                 </firewall>
@@ -321,8 +339,6 @@ Configuration example for form login
             'firewalls' => array(
                 'main' => array(
                     'form_login_ldap' => array(
-                        'login_path' => 'login',
-                        'check_path' => 'login_check',
                         'service' => 'ldap',
                         'dn_string' => 'uid={username},dc=example,dc=com',
                         // ...
@@ -382,5 +398,61 @@ Configuration example for HTTP Basic
             ),
         );
 
+Configuration example for form login and query_string
+.....................................................
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+
+            firewalls:
+                main:
+                    # ...
+                    form_login_ldap:
+                        # ...
+                        service: ldap
+                        dn_string: 'dc=example,dc=com'
+                        query_string: '(&(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))'
+
+    .. code-block:: xml
+
+        <!-- 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="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>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'main' => array(
+                    'form_login_ldap' => array(
+                        'service' => 'ldap',
+                        'dn_string' => 'dc=example,dc=com',
+                        'query_string' => '(&(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))',
+                        // ...
+                    ),
+                ),
+            )
+        );
+
 .. _`RFC4515`: http://www.faqs.org/rfcs/rfc4515.html
 .. _`LDAP injection`: http://projects.webappsec.org/w/page/13246947/LDAP%20Injection