Merge branch 'doc-omniauth-ldap-limitations' into 'master'

Documentation of omniauth-ldap limitations

Further documentation about limitations directly impacting settings of
users' LDAP servers.

Closes #2613

See merge request !1421

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md
index 3bc5df21ef4..9b7d8fa3969 100644
--- a/doc/integration/ldap.md
+++ b/doc/integration/ldap.md
@@ -173,3 +173,23 @@ Tip: if you want to limit access to the nested members of an Active Directory gr
 ```
 
 Please note that GitLab does not support the custom filter syntax used by omniauth-ldap.
+
+## Limitations
+
+GitLab's LDAP client is based on [omniauth-ldap](https://gitlab.com/gitlab-org/omniauth-ldap)
+which encapsulates Ruby's `Net::LDAP` class. It provides a pure-Ruby implementation
+of the LDAP client protocol. As a result, GitLab is limited by `omniauth-ldap` and may impact your LDAP 
+server settings.
+
+### TLS Client Authentication  
+Not implemented by `Net::LDAP`.  
+So you should disable anonymous LDAP authentication and enable simple or SASL 
+authentication. TLS client authentication setting in your LDAP server cannot be
+mandatory and clients cannot be authenticated with the TLS protocol. 
+
+### TLS Server Authentication  
+Not supported by GitLab's configuration options.  
+When setting `method: ssl`, the underlying authentication method used by 
+`omniauth-ldap` is `simple_tls`.  This method establishes TLS encryption with 
+the LDAP server before any LDAP-protocol data is exchanged but no validation of
+the LDAP server's SSL certificate is performed.
\ No newline at end of file