Merge branch 'gitlab_ldap_filter' into 'master'

Add more LDAP user_filter documentation

See merge request !1115

config/gitlab.yml.example

@@ -159,9 +159,11 @@ production: &base
     # Filter LDAP users
     #
-    #   Format: RFC 4515
+    #   Format: RFC 4515 http://tools.ietf.org/search/rfc4515
     #   Ex. (employeeType=developer)
     #
+    #   Note: GitLab does not support omniauth-ldap's custom filter syntax.
+    #
     user_filter: ''

doc/integration/ldap.md

@@ -17,3 +17,28 @@ In other words, if an existing GitLab user wants to enable LDAP sign-in for them
 GitLab recognizes the following LDAP attributes as email addresses: `mail`, `email` and `userPrincipalName`.
 If multiple LDAP email attributes are present, e.g. `mail: foo@bar.com` and `email: foo@example.com`, then the first attribute found wins -- in this case `foo@bar.com`.
+
+## Using an LDAP filter to limit access to your GitLab server
+
+If you want to limit all GitLab access to a subset of the LDAP users on your LDAP server you can set up an LDAP user filter.
+The filter must comply with [RFC 4515](http://tools.ietf.org/search/rfc4515).
+
+```ruby
+# For omnibus-gitlab
+gitlab_rails['ldap_user_filter'] = '(employeeType=developer)'
+```
+
+```yaml
+# For installations from source
+production:
+  ldap:
+     user_filter: '(employeeType=developer)'
+```
+
+Tip: if you want to limit access to the nested members of an Active Directory group you can use the following syntax:
+
+```
+(memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com)
+```
+
+Please note that GitLab does not support the custom filter syntax used by omniauth-ldap.