Merge branch 'add-ldap-ssl-certificate-verification-9-4' into '9-4-stable-patch-2'

Add LDAP SSL certificate verification [9.4]

See merge request !13107

2 files changed, 51 insertions, 17 deletions

diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md
index 725fc1f6076..8ff59ee652c 100644
--- a/doc/administration/auth/ldap.md
+++ b/doc/administration/auth/ldap.md
@@ -69,14 +69,42 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server
   # Example: 'ldap.mydomain.com'
   host: '_your_ldap_server'
   # This port is an example, it is sometimes different but it is always an integer and not a string
-  port: 389
+  port: 389 # usually 636 for SSL
   uid: 'sAMAccountName' # This should be the attribute, not the value that maps to uid.
-  method: 'plain' # "tls" or "ssl" or "plain"
 
   # Examples: 'america\\momo' or 'CN=Gitlab Git,CN=Users,DC=mydomain,DC=com'
   bind_dn: '_the_full_dn_of_the_user_you_will_bind_with'
   password: '_the_password_of_the_bind_user'
 
+  # Encryption method. The "method" key is deprecated in favor of
+  # "encryption".
+  #
+  #   Examples: "start_tls" or "simple_tls" or "plain"
+  #
+  #   Deprecated values: "tls" was replaced with "start_tls" and "ssl" was
+  #   replaced with "simple_tls".
+  #
+  encryption: 'plain'
+
+  # Enables SSL certificate verification if encryption method is
+  # "start_tls" or "simple_tls". (Defaults to false for backward-
+  # compatibility)
+  verify_certificates: false
+
+  # Specifies the path to a file containing a PEM-format CA certificate,
+  # e.g. if you need to use an internal CA.
+  #
+  #   Example: '/etc/ca.pem'
+  #
+  ca_cert: ''
+
+  # Specifies the SSL version for OpenSSL to use, if the OpenSSL default
+  # is not appropriate.
+  #
+  #   Example: 'TLSv1_1'
+  #
+  ssl_version: ''
+
   # Set a timeout, in seconds, for LDAP queries. This helps avoid blocking
   # a request if the LDAP server becomes unresponsive.
   # A value of 0 means there is no timeout.
@@ -116,8 +144,8 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server
   #
   #   Note: GitLab does not support omniauth-ldap's custom filter syntax.
   #
-  #   Below an example for get only specific users
-  #   Example: '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
+  #   Example for getting only specific users:
+  #   '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
   #
   user_filter: ''
 
@@ -245,6 +273,19 @@ In other words, if an existing GitLab user wants to enable LDAP sign-in for
 themselves, they should check that their GitLab email address matches their
 LDAP email address, and then sign into GitLab via their LDAP credentials.
 
+## Encryption
+
+### TLS Server Authentication
+
+There are two encryption methods, `simple_tls` and `start_tls`.
+
+For either encryption method, if setting `validate_certificates: false`, TLS
+encryption is established with the LDAP server before any LDAP-protocol data is
+exchanged but no validation of the LDAP server's SSL certificate is performed.
+
+>**Note**: Before GitLab 9.5, `validate_certificates: false` is the default if
+unspecified.
+
 ## Limitations
 
 ### TLS Client Authentication
@@ -254,14 +295,6 @@ You should disable anonymous LDAP authentication and enable simple or SASL
 authentication. The 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.
-
 ## Troubleshooting
 
 ### Debug LDAP user filter with ldapsearch
@@ -301,9 +334,9 @@ tree and traverse it.
 ### Connection Refused
 
 If you are getting 'Connection Refused' errors when trying to connect to the
-LDAP server please double-check the LDAP `port` and `method` settings used by
-GitLab. Common combinations are `method: 'plain'` and `port: 389`, OR
-`method: 'ssl'` and `port: 636`.
+LDAP server please double-check the LDAP `port` and `encryption` settings used by
+GitLab. Common combinations are `encryption: 'plain'` and `port: 389`, OR
+`encryption: 'simple_tls'` and `port: 636`.
 
 ### Troubleshooting
 
diff --git a/doc/articles/how_to_configure_ldap_gitlab_ce/index.md b/doc/articles/how_to_configure_ldap_gitlab_ce/index.md
index 6892905dd94..130e8f542b4 100644
--- a/doc/articles/how_to_configure_ldap_gitlab_ce/index.md
+++ b/doc/articles/how_to_configure_ldap_gitlab_ce/index.md
@@ -120,7 +120,8 @@ gitlab_rails['ldap_servers'] = {
   'host' =>  'ad.example.org',
   'port' => 636,
   'uid' => 'sAMAccountName',
-  'method' => 'ssl',
+  'encryption' => 'simple_tls',
+  'verify_certificates' => true,
   'bind_dn' => 'CN=GitLabSRV,CN=Users,DC=GitLab,DC=org',
   'password' => 'Password1',
   'active_directory' => true,
@@ -255,7 +256,7 @@ If `allow_username_or_email_login` is enabled in the LDAP configuration, GitLab
 
 ## LDAP extended features on GitLab EE
 
-With [GitLab Enterprise Edition (EE)](https://about.gitlab.com/giltab-ee/), besides everything we just described, you'll
+With [GitLab Enterprise Edition (EE)](https://about.gitlab.com/gitlab-ee/), besides everything we just described, you'll
 have extended functionalities with LDAP, such as:
 
 - Group sync