Merge remote-tracking branch 'nietonfir/ldap_security' into ldap_query_string

Author: lsmith77

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

security/ldap.rst

@@ -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``.