Add latest changes from gitlab-org/gitlab@13-1-stable-ee

7 files changed, 1656 insertions, 0 deletions

diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md
new file mode 100644
index 00000000000..2271ce93b6f
--- /dev/null
+++ b/doc/administration/auth/ldap/google_secure_ldap.md
@@ -0,0 +1,222 @@
+---
+type: reference
+stage: Manage
+group: Access
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Google Secure LDAP **(CORE ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46391) in GitLab 11.9.
+
+[Google Cloud Identity](https://cloud.google.com/identity/) provides a Secure
+LDAP service that can be configured with GitLab for authentication and group sync.
+
+Secure LDAP requires a slightly different configuration than standard LDAP servers.
+The steps below cover:
+
+- Configuring the Secure LDAP Client in the Google Admin console.
+- Required GitLab configuration.
+
+## Configuring Google LDAP client
+
+1. Navigate to <https://admin.google.com/Dashboard> and sign in as a GSuite domain administrator.
+
+1. Go to **Apps > LDAP > Add Client**.
+
+1. Provide an `LDAP client name` and an optional `Description`. Any descriptive
+   values are acceptable. For example, the name could be 'GitLab' and the
+   description could be 'GitLab LDAP Client'. Click the **Continue** button.
+
+   ![Add LDAP Client Step 1](img/google_secure_ldap_add_step_1.png)
+
+1. Set **Access Permission** according to your needs. You must choose either
+   'Entire domain (GitLab)' or 'Selected organizational units' for both 'Verify user
+   credentials' and 'Read user information'. Select 'Add LDAP Client'
+
+   TIP: **Tip:** If you plan to use GitLab [LDAP Group Sync](index.md#group-sync-starter-only)
+   , turn on 'Read group information'.
+
+   ![Add LDAP Client Step 2](img/google_secure_ldap_add_step_2.png)
+
+1. Download the generated certificate. This is required for GitLab to
+   communicate with the Google Secure LDAP service. Save the downloaded certificates
+   for later use. After downloading, click the **Continue to Client Details** button.
+
+1. Expand the **Service Status** section and turn the LDAP client 'ON for everyone'.
+   After selecting 'Save', click on the 'Service Status' bar again to collapse
+   and return to the rest of the settings.
+
+1. Expand the **Authentication** section and choose 'Generate New Credentials'.
+   Copy/note these credentials for later use. After selecting 'Close', click
+   on the 'Authentication' bar again to collapse and return to the rest of the settings.
+
+Now the Google Secure LDAP Client configuration is finished. The screenshot below
+shows an example of the final settings. Continue on to configure GitLab.
+
+![LDAP Client Settings](img/google_secure_ldap_client_settings.png)
+
+## Configuring GitLab
+
+Edit GitLab configuration, inserting the access credentials and certificate
+obtained earlier.
+
+The following are the configuration keys that need to be modified using the
+values obtained during the LDAP client configuration earlier:
+
+- `bind_dn`: The access credentials username
+- `password`: The access credentials password
+- `cert`: The `.crt` file text from the downloaded certificate bundle
+- `key`: The `.key` file text from the downloaded certificate bundle
+
+**For Omnibus installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['ldap_enabled'] = true
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS # remember to close this block with 'EOS' below
+     main: # 'main' is the GitLab 'provider ID' of this LDAP server
+       label: 'Google Secure LDAP'
+
+       host: 'ldap.google.com'
+       port: 636
+       uid: 'uid'
+       bind_dn: 'DizzyHorse'
+       password: 'd6V5H8nhMUW9AuDP25abXeLd'
+       encryption: 'simple_tls'
+       verify_certificates: true
+
+       tls_options:
+         cert: |
+           -----BEGIN CERTIFICATE-----
+           MIIDbDCCAlSgAwIBAgIGAWlzxiIfMA0GCSqGSIb3DQEBCwUAMHcxFDASBgNVBAoTC0dvb2dsZSBJ
+           bmMuMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQDEwtMREFQIENsaWVudDEPMA0GA1UE
+           CxMGR1N1aXRlMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTAeFw0xOTAzMTIyMTE5
+           MThaFw0yMjAzMTEyMTE5MThaMHcxFDASBgNVBAoTC0dvb2dsZSBJbmMuMRYwFAYDVQQHEw1Nb3Vu
+           dGFpbiBWaWV3MRQwEgYDVQQDEwtMREFQIENsaWVudDEPMA0GA1UECxMGR1N1aXRlMQswCQYDVQQG
+           EwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
+           ALOTy4aC38dyjESk6N8fRsKk8DN23ZX/GaNFL5OUmmA1KWzrvVC881OzNdtGm3vNOIxr9clteEG/
+           tQwsmsJvQT5U+GkBt+tGKF/zm7zueHUYqTP7Pg5pxAnAei90qkIRFi17ulObyRHPYv1BbCt8pxNB
+           4fG/gAXkFbCNxwh1eiQXXRTfruasCZ4/mHfX7MVm8JmWU9uAVIOLW+DSWOFhrDQduJdGBXJOyC2r
+           Gqoeg9+tkBmNH/jjxpnEkFW8q7io9DdOUqqNgoidA1h9vpKTs3084sy2DOgUvKN9uXWx14uxIyYU
+           Y1DnDy0wczcsuRt7l+EgtCEgpsLiLJQbKW+JS1UCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAf60J
+           yazhbHkDKIH2gFxfm7QLhhnqsmafvl4WP7JqZt0u0KdnvbDPfokdkM87yfbKJU1MTI86M36wEC+1
+           P6bzklKz7kXbzAD4GggksAzxsEE64OWHC+Y64Tkxq2NiZTw/76POkcg9StiIXjG0ZcebHub9+Ux/
+           rTncip92nDuvgEM7lbPFKRIS/YMhLCk09B/U0F6XLsf1yYjyf5miUTDikPkov23b/YGfpc8kh6hq
+           1kqdi6a1cYPP34eAhtRhMqcZU9qezpJF6s9EeN/3YFfKzLODFSsVToBRAdZgGHzj//SAtLyQTD4n
+           KCSvK1UmaMxNaZyTHg8JnMf0ZuRpv26iSg==
+           -----END CERTIFICATE-----
+
+         key: |
+           -----BEGIN PRIVATE KEY-----
+           MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCzk8uGgt/HcoxEpOjfH0bCpPAz
+           dt2V/xmjRS+TlJpgNSls671QvPNTszXbRpt7zTiMa/XJbXhBv7UMLJrCb0E+VPhpAbfrRihf85u8
+           7nh1GKkz+z4OacQJwHovdKpCERYte7pTm8kRz2L9QWwrfKcTQeHxv4AF5BWwjccIdXokF10U367m
+           rAmeP5h31+zFZvCZllPbgFSDi1vg0ljhYaw0HbiXRgVyTsgtqxqqHoPfrZAZjR/448aZxJBVvKu4
+           qPQ3TlKqjYKInQNYfb6Sk7N9POLMtgzoFLyjfbl1sdeLsSMmFGNQ5w8tMHM3LLkbe5fhILQhIKbC
+           4iyUGylviUtVAgMBAAECggEAIPb0CQy0RJoX+q/lGbRVmnyJpYDf+115WNnl+mrwjdGkeZyqw4v0
+           BPzkWYzUFP1esJRO6buBNFybQRFdFW0z5lvVv/zzRKq71aVUBPInxaMRyHuJ8D5lIL8nDtgVOwyE
+           7DOGyDtURUMzMjdUwoTe7K+O6QBU4X/1pVPZYgmissYSMmt68LiP8k0p601F4+r5xOi/QEy44aVp
+           aOJZBUOisKB8BmUXZqmQ4Cy05vU9Xi1rLyzkn9s7fxnZ+JO6Sd1r0Thm1mE0yuPgxkDBh/b4f3/2
+           GsQNKKKCiij/6TfkjnBi8ZvWR44LnKpu760g/K7psVNrKwqJG6C/8RAcgISWQQKBgQDop7BaKGhK
+           1QMJJ/vnlyYFTucfGLn6bM//pzTys5Gop0tpcfX/Hf6a6Dd+zBhmC3tBmhr80XOX/PiyAIbc0lOI
+           31rafZuD/oVx5mlIySWX35EqS14LXmdVs/5vOhsInNgNiE+EPFf1L9YZgG/zA7OUBmqtTeYIPDVC
+           7ViJcydItQKBgQDFmK0H0IA6W4opGQo+zQKhefooqZ+RDk9IIZMPOAtnvOM7y3rSVrfsSjzYVuMS
+           w/RP/vs7rwhaZejnCZ8/7uIqwg4sdUBRzZYR3PRNFeheW+BPZvb+2keRCGzOs7xkbF1mu54qtYTa
+           HZGZj1OsD83AoMwVLcdLDgO1kw32dkS8IQKBgFRdgoifAHqqVah7VFB9se7Y1tyi5cXWsXI+Wufr
+           j9U9nQ4GojK52LqpnH4hWnOelDqMvF6TQTyLIk/B+yWWK26Ft/dk9wDdSdystd8L+dLh4k0Y+Whb
+           +lLMq2YABw+PeJUnqdYE38xsZVHoDjBsVjFGRmbDybeQxauYT7PACy3FAoGBAK2+k9bdNQMbXp7I
+           j8OszHVkJdz/WXlY1cmdDAxDwXOUGVKIlxTAf7TbiijILZ5gg0Cb+hj+zR9/oI0WXtr+mAv02jWp
+           W8cSOLS4TnBBpTLjIpdu+BwbnvYeLF6MmEjNKEufCXKQbaLEgTQ/XNlchBSuzwSIXkbWqdhM1+gx
+           EjtBAoGARAdMIiDMPWIIZg3nNnFebbmtBP0qiBsYohQZ+6i/8s/vautEHBEN6Q0brIU/goo+nTHc
+           t9VaOkzjCmAJSLPUanuBC8pdYgLu5J20NXUZLD9AE/2bBT3OpezKcdYeI2jqoc1qlWHlNtVtdqQ2
+           AcZSFJQjdg5BTyvdEDhaYUKGdRw=
+           -----END PRIVATE KEY-----
+   EOS
+   ```
+
+1. Save the file and [reconfigure](../../restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect.
+
+---
+
+**For installations from source**
+
+1. Edit `config/gitlab.yml`:
+
+   ```yaml
+   ldap:
+     enabled: true
+     servers:
+       main: # 'main' is the GitLab 'provider ID' of this LDAP server
+         label: 'Google Secure LDAP'
+
+         host: 'ldap.google.com'
+         port: 636
+         uid: 'uid'
+         bind_dn: 'DizzyHorse'
+         password: 'd6V5H8nhMUW9AuDP25abXeLd'
+         encryption: 'simple_tls'
+         verify_certificates: true
+
+         tls_options:
+           cert: |
+             -----BEGIN CERTIFICATE-----
+             MIIDbDCCAlSgAwIBAgIGAWlzxiIfMA0GCSqGSIb3DQEBCwUAMHcxFDASBgNVBAoTC0dvb2dsZSBJ
+             bmMuMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQDEwtMREFQIENsaWVudDEPMA0GA1UE
+             CxMGR1N1aXRlMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTAeFw0xOTAzMTIyMTE5
+             MThaFw0yMjAzMTEyMTE5MThaMHcxFDASBgNVBAoTC0dvb2dsZSBJbmMuMRYwFAYDVQQHEw1Nb3Vu
+             dGFpbiBWaWV3MRQwEgYDVQQDEwtMREFQIENsaWVudDEPMA0GA1UECxMGR1N1aXRlMQswCQYDVQQG
+             EwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
+             ALOTy4aC38dyjESk6N8fRsKk8DN23ZX/GaNFL5OUmmA1KWzrvVC881OzNdtGm3vNOIxr9clteEG/
+             tQwsmsJvQT5U+GkBt+tGKF/zm7zueHUYqTP7Pg5pxAnAei90qkIRFi17ulObyRHPYv1BbCt8pxNB
+             4fG/gAXkFbCNxwh1eiQXXRTfruasCZ4/mHfX7MVm8JmWU9uAVIOLW+DSWOFhrDQduJdGBXJOyC2r
+             Gqoeg9+tkBmNH/jjxpnEkFW8q7io9DdOUqqNgoidA1h9vpKTs3084sy2DOgUvKN9uXWx14uxIyYU
+             Y1DnDy0wczcsuRt7l+EgtCEgpsLiLJQbKW+JS1UCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAf60J
+             yazhbHkDKIH2gFxfm7QLhhnqsmafvl4WP7JqZt0u0KdnvbDPfokdkM87yfbKJU1MTI86M36wEC+1
+             P6bzklKz7kXbzAD4GggksAzxsEE64OWHC+Y64Tkxq2NiZTw/76POkcg9StiIXjG0ZcebHub9+Ux/
+             rTncip92nDuvgEM7lbPFKRIS/YMhLCk09B/U0F6XLsf1yYjyf5miUTDikPkov23b/YGfpc8kh6hq
+             1kqdi6a1cYPP34eAhtRhMqcZU9qezpJF6s9EeN/3YFfKzLODFSsVToBRAdZgGHzj//SAtLyQTD4n
+             KCSvK1UmaMxNaZyTHg8JnMf0ZuRpv26iSg==
+             -----END CERTIFICATE-----
+
+           key: |
+             -----BEGIN PRIVATE KEY-----
+             MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCzk8uGgt/HcoxEpOjfH0bCpPAz
+             dt2V/xmjRS+TlJpgNSls671QvPNTszXbRpt7zTiMa/XJbXhBv7UMLJrCb0E+VPhpAbfrRihf85u8
+             7nh1GKkz+z4OacQJwHovdKpCERYte7pTm8kRz2L9QWwrfKcTQeHxv4AF5BWwjccIdXokF10U367m
+             rAmeP5h31+zFZvCZllPbgFSDi1vg0ljhYaw0HbiXRgVyTsgtqxqqHoPfrZAZjR/448aZxJBVvKu4
+             qPQ3TlKqjYKInQNYfb6Sk7N9POLMtgzoFLyjfbl1sdeLsSMmFGNQ5w8tMHM3LLkbe5fhILQhIKbC
+             4iyUGylviUtVAgMBAAECggEAIPb0CQy0RJoX+q/lGbRVmnyJpYDf+115WNnl+mrwjdGkeZyqw4v0
+             BPzkWYzUFP1esJRO6buBNFybQRFdFW0z5lvVv/zzRKq71aVUBPInxaMRyHuJ8D5lIL8nDtgVOwyE
+             7DOGyDtURUMzMjdUwoTe7K+O6QBU4X/1pVPZYgmissYSMmt68LiP8k0p601F4+r5xOi/QEy44aVp
+             aOJZBUOisKB8BmUXZqmQ4Cy05vU9Xi1rLyzkn9s7fxnZ+JO6Sd1r0Thm1mE0yuPgxkDBh/b4f3/2
+             GsQNKKKCiij/6TfkjnBi8ZvWR44LnKpu760g/K7psVNrKwqJG6C/8RAcgISWQQKBgQDop7BaKGhK
+             1QMJJ/vnlyYFTucfGLn6bM//pzTys5Gop0tpcfX/Hf6a6Dd+zBhmC3tBmhr80XOX/PiyAIbc0lOI
+             31rafZuD/oVx5mlIySWX35EqS14LXmdVs/5vOhsInNgNiE+EPFf1L9YZgG/zA7OUBmqtTeYIPDVC
+             7ViJcydItQKBgQDFmK0H0IA6W4opGQo+zQKhefooqZ+RDk9IIZMPOAtnvOM7y3rSVrfsSjzYVuMS
+             w/RP/vs7rwhaZejnCZ8/7uIqwg4sdUBRzZYR3PRNFeheW+BPZvb+2keRCGzOs7xkbF1mu54qtYTa
+             HZGZj1OsD83AoMwVLcdLDgO1kw32dkS8IQKBgFRdgoifAHqqVah7VFB9se7Y1tyi5cXWsXI+Wufr
+             j9U9nQ4GojK52LqpnH4hWnOelDqMvF6TQTyLIk/B+yWWK26Ft/dk9wDdSdystd8L+dLh4k0Y+Whb
+             +lLMq2YABw+PeJUnqdYE38xsZVHoDjBsVjFGRmbDybeQxauYT7PACy3FAoGBAK2+k9bdNQMbXp7I
+             j8OszHVkJdz/WXlY1cmdDAxDwXOUGVKIlxTAf7TbiijILZ5gg0Cb+hj+zR9/oI0WXtr+mAv02jWp
+             W8cSOLS4TnBBpTLjIpdu+BwbnvYeLF6MmEjNKEufCXKQbaLEgTQ/XNlchBSuzwSIXkbWqdhM1+gx
+             EjtBAoGARAdMIiDMPWIIZg3nNnFebbmtBP0qiBsYohQZ+6i/8s/vautEHBEN6Q0brIU/goo+nTHc
+             t9VaOkzjCmAJSLPUanuBC8pdYgLu5J20NXUZLD9AE/2bBT3OpezKcdYeI2jqoc1qlWHlNtVtdqQ2
+             AcZSFJQjdg5BTyvdEDhaYUKGdRw=
+             -----END PRIVATE KEY-----
+   ```
+
+1. Save the file and [restart](../../restart_gitlab.md#installations-from-source) GitLab for the changes to take effect.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/administration/auth/ldap/img/google_secure_ldap_add_step_1.png b/doc/administration/auth/ldap/img/google_secure_ldap_add_step_1.png
new file mode 100644
index 00000000000..bee9c602a14
--- /dev/null
+++ b/doc/administration/auth/ldap/img/google_secure_ldap_add_step_1.png
diff --git a/doc/administration/auth/ldap/img/google_secure_ldap_add_step_2.png b/doc/administration/auth/ldap/img/google_secure_ldap_add_step_2.png
new file mode 100644
index 00000000000..b127410cb8c
--- /dev/null
+++ b/doc/administration/auth/ldap/img/google_secure_ldap_add_step_2.png
diff --git a/doc/administration/auth/ldap/img/google_secure_ldap_client_settings.png b/doc/administration/auth/ldap/img/google_secure_ldap_client_settings.png
new file mode 100644
index 00000000000..868e6645f56
--- /dev/null
+++ b/doc/administration/auth/ldap/img/google_secure_ldap_client_settings.png
diff --git a/doc/administration/auth/ldap/img/multi_login.gif b/doc/administration/auth/ldap/img/multi_login.gif
new file mode 100644
index 00000000000..5aee6090793
--- /dev/null
+++ b/doc/administration/auth/ldap/img/multi_login.gif
diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md
new file mode 100644
index 00000000000..4a7a972596f
--- /dev/null
+++ b/doc/administration/auth/ldap/index.md
@@ -0,0 +1,756 @@
+---
+type: reference
+stage: Manage
+group: Access
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# General LDAP Setup
+
+GitLab integrates with LDAP to support user authentication.
+
+This integration works with most LDAP-compliant directory servers, including:
+
+- Microsoft Active Directory
+- Apple Open Directory
+- Open LDAP
+- 389 Server
+
+GitLab Enterprise Editions (EE) include enhanced integration,
+including group membership syncing as well as multiple LDAP servers support.
+
+NOTE: **Note:**
+[Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) are not supported.
+
+## Overview
+
+[LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
+stands for **Lightweight Directory Access Protocol**, which is a standard
+application protocol for accessing and maintaining distributed directory
+information services over an Internet Protocol (IP) network.
+
+## Security **(CORE ONLY)**
+
+GitLab assumes that LDAP users:
+
+- Are not able to change their LDAP `mail`, `email`, or `userPrincipalName` attributes.
+  An LDAP user who is allowed to change their email on the LDAP server can potentially
+  [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users-core-only)
+  on your GitLab server.
+- Have unique email addresses, otherwise it is possible for LDAP users with the same
+  email address to share the same GitLab account.
+
+We recommend against using LDAP integration if your LDAP users are
+allowed to change their 'mail', 'email' or 'userPrincipalName' attribute on
+the LDAP server or share email addresses.
+
+### User deletion **(CORE ONLY)**
+
+If a user is deleted from the LDAP server, they will be blocked in GitLab as
+well. Users will be immediately blocked from logging in. However, there is an
+LDAP check cache time of one hour (see note) which means users that
+are already logged in or are using Git over SSH will still be able to access
+GitLab for up to one hour. Manually block the user in the GitLab Admin Area to
+immediately block all access.
+
+NOTE: **Note**:
+GitLab Enterprise Edition Starter supports a
+[configurable sync time](#adjusting-ldap-user-sync-schedule-starter-only).
+
+## Git password authentication **(CORE ONLY)**
+
+LDAP-enabled users can always authenticate with Git using their GitLab username
+or email and LDAP password, even if password authentication for Git is disabled
+in the application settings.
+
+## Enabling LDAP sign-in for existing GitLab users **(CORE ONLY)**
+
+When a user signs in to GitLab with LDAP for the first time, and their LDAP
+email address is the primary email address of an existing GitLab user, then
+the LDAP DN will be associated with the existing user. If the LDAP email
+attribute is not found in GitLab's database, a new user is created.
+
+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.
+
+## Google Secure LDAP **(CORE ONLY)**
+
+> Introduced in GitLab 11.9.
+
+[Google Cloud Identity](https://cloud.google.com/identity/) provides a Secure
+LDAP service that can be configured with GitLab for authentication and group sync.
+See [Google Secure LDAP](google_secure_ldap.md) for detailed configuration instructions.
+
+## Configuration **(CORE ONLY)**
+
+To enable LDAP integration you need to add your LDAP server settings in
+`/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml` for Omnibus
+GitLab and installations from source respectively.
+
+There is a Rake task to check LDAP configuration. After configuring LDAP
+using the documentation below, see [LDAP check Rake task](../../raketasks/check.md#ldap-check)
+for information on the LDAP check Rake task.
+
+NOTE: **Note:**
+The `encryption` value `simple_tls` corresponds to 'Simple TLS' in the LDAP
+library. `start_tls` corresponds to StartTLS, not to be confused with regular TLS.
+Normally, if you specify `simple_tls` it will be on port 636, while `start_tls` (StartTLS)
+would be on port 389. `plain` also operates on port 389. Removed values: `tls` was replaced with `start_tls` and `ssl` was replaced with `simple_tls`.
+
+NOTE: **Note:**
+LDAP users must have an email address set, regardless of whether it is used to log in.
+
+### Example Configurations **(CORE ONLY)**
+
+**Omnibus Configuration**
+
+```ruby
+gitlab_rails['ldap_enabled'] = true
+gitlab_rails['prevent_ldap_sign_in'] = false
+gitlab_rails['ldap_servers'] = {
+'main' => {
+  'label' => 'LDAP',
+  'host' =>  'ldap.mydomain.com',
+  'port' => 389,
+  'uid' => 'sAMAccountName',
+  'encryption' => 'simple_tls',
+  'verify_certificates' => true,
+  'bind_dn' => '_the_full_dn_of_the_user_you_will_bind_with',
+  'password' => '_the_password_of_the_bind_user',
+  'encryption' => 'plain',
+  'verify_certificates' => true,
+  'tls_options' => {
+    'ca_file' => '',
+    'ssl_version' => '',
+    'ciphers' => '',
+    'cert' => '',
+    'key' => ''
+  },
+  'timeout' => 10,
+  'active_directory' => true,
+  'allow_username_or_email_login' => false,
+  'block_auto_created_users' => false,
+  'base' => 'dc=example,dc=com',
+  'user_filter' => '',
+  'attributes' => {
+    'username' => ['uid', 'userid', 'sAMAccountName'],
+    'email' => ['mail', 'email', 'userPrincipalName'],
+    'name' => 'cn',
+    'first_name' => 'givenName',
+    'last_name' => 'sn'
+  },
+  'lowercase_usernames' => false,
+
+  # EE Only
+  'group_base' => '',
+  'admin_group' => '',
+  'external_groups' => [],
+  'sync_ssh_keys' => false
+  }
+}
+```
+
+**Source Configuration**
+
+```yaml
+production:
+  # snip...
+  ldap:
+    enabled: false
+    prevent_ldap_sign_in: false
+    servers:
+      main:
+        label: 'LDAP'
+        ...
+```
+
+### Basic Configuration Settings **(CORE ONLY)**
+
+| Setting | Description | Required | Examples |
+| ------- | ----------- | -------- | -------- |
+| `label` | A human-friendly name for your LDAP server. It will be displayed on your login page. | yes | `'Paris'` or `'Acme, Ltd.'` |
+| `host`  | IP address or domain name of your LDAP server. | yes | `'ldap.mydomain.com'` |
+| `port`  | The port to connect with on your LDAP server. Always an integer, not a string. | yes | `389` or `636` (for SSL) |
+| `uid`   | LDAP attribute for username. Should be the attribute, not the value that maps to the `uid`. | yes | `'sAMAccountName'`, `'uid'`, `'userPrincipalName'` |
+| `bind_dn` | The full DN of the user you will bind with. | no | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` |
+| `password` | The password of the bind user. | no | `'your_great_password'` |
+| `encryption` | Encryption method. The `method` key is deprecated in favor of `encryption`. | yes | `'start_tls'` or `'simple_tls'` or `'plain'` |
+| `verify_certificates` | Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. Defaults to true. | no | boolean |
+| `timeout` | 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. | no | `10` or `30` |
+| `active_directory` | This setting specifies if LDAP server is Active Directory LDAP server. For non-AD servers it skips the AD specific queries. If your LDAP server is not AD, set this to false. | no | boolean |
+| `allow_username_or_email_login` | If enabled, GitLab will ignore everything after the first `@` in the LDAP username submitted by the user on login. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you need to disable this setting, because the userPrincipalName contains an `@`. | no | boolean |
+| `block_auto_created_users` | To maintain tight control over the number of active users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by the admin (default: false). | no | boolean |
+| `base` | Base where we can search for users. | yes | `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` |
+| `user_filter` | Filter LDAP users. Format: [RFC 4515](https://tools.ietf.org/search/rfc4515) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | no | `'(employeeType=developer)'` or `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` |
+| `lowercase_usernames` | If lowercase_usernames is enabled, GitLab will lower case the username. | no | boolean |
+
+### SSL Configuration Settings **(CORE ONLY)**
+
+| Setting | Description | Required | Examples |
+| ------- | ----------- | -------- | -------- |
+| `ca_file` | Specifies the path to a file containing a PEM-format CA certificate, e.g. if you need to use an internal CA. | no | `'/etc/ca.pem'` |
+| `ssl_version` | Specifies the SSL version for OpenSSL to use, if the OpenSSL default is not appropriate. | no | `'TLSv1_1'` |
+| `ciphers` | Specific SSL ciphers to use in communication with LDAP servers. | no | `'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'` |
+| `cert` | Client certificate | no | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` |
+| `key` | Client private key | no | `'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'` |
+
+### Attribute Configuration Settings **(CORE ONLY)**
+
+LDAP attributes that GitLab will use to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (e.g. `'mail'`), or an array of attribute names to try in order (e.g. `['mail', 'email']`). Note that the user's LDAP login will always be the attribute specified as `uid` above.
+
+| Setting | Description | Required | Examples |
+| ------- | ----------- | -------- | -------- |
+| `username` | The username will be used in paths for the user's own projects (like `gitlab.example.com/username/project`) and when mentioning them in issues, merge request and comments (like `@username`). If the attribute specified for `username` contains an email address, the GitLab username will be the part of the email address before the `@`. | no | `['uid', 'userid', 'sAMAccountName']` |
+| `email` | LDAP attribute for user email. | no | `['mail', 'email', 'userPrincipalName']` |
+| `name` | LDAP attribute for user display name. If no full name could be found at the attribute specified for `name`, the full name is determined using the attributes specified for `first_name` and `last_name`. | no | `'cn'` or `'displayName'` |
+| `first_name` | LDAP attribute for user first name. | no | `'givenName'` |
+| `last_name` | LDAP attribute for user last name. | no | `'sn'` |
+
+### LDAP Sync Configuration Settings **(STARTER ONLY)**
+
+| Setting | Description | Required | Examples |
+| ------- | ----------- | -------- | -------- |
+| `group_base` | Base used to search for groups. | no | `'ou=groups,dc=gitlab,dc=example'` |
+| `admin_group` | The CN of a group containing GitLab administrators. Note: Not `cn=administrators` or the full DN. | no | `'administrators'` |
+| `external_groups` | An array of CNs of groups containing users that should be considered external. Note: Not `cn=interns` or the full DN. | no | `['interns', 'contractors']` |
+| `sync_ssh_keys` | The LDAP attribute containing a user's public SSH key. | no | `'sshPublicKey'` or false if not set |
+
+### Set up LDAP user filter **(CORE ONLY)**
+
+If you want to limit all GitLab access to a subset of the LDAP users on your
+LDAP server, the first step should be to narrow the configured `base`. However,
+it is sometimes necessary to filter users further. In this case, you can set up
+an LDAP user filter. The filter must comply with
+[RFC 4515](https://tools.ietf.org/search/rfc4515).
+
+**Omnibus configuration**
+
+```ruby
+gitlab_rails['ldap_servers'] = {
+'main' => {
+  # snip...
+  'user_filter' => '(employeeType=developer)'
+  }
+}
+```
+
+**Source configuration**
+
+```yaml
+production:
+  ldap:
+    servers:
+      main:
+        # snip...
+        user_filter: '(employeeType=developer)'
+```
+
+If you want to limit access to the nested members of an Active Directory
+group, you can use the following syntax:
+
+```plaintext
+(memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com)
+```
+
+For more information about this "LDAP_MATCHING_RULE_IN_CHAIN" filter, see the following
+[Microsoft Search Filter Syntax](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) document.
+Support for nested members in the user filter should not be confused with
+[group sync nested groups support](#supported-ldap-group-typesattributes). **(STARTER ONLY)**
+
+Please note that GitLab does not support the custom filter syntax used by
+OmniAuth LDAP.
+
+#### Escaping special characters **(CORE ONLY)**
+
+The `user_filter` DN can contain special characters. For example:
+
+- A comma:
+
+  ```plaintext
+  OU=GitLab, Inc,DC=gitlab,DC=com
+  ```
+
+- Open and close brackets:
+
+  ```plaintext
+  OU=Gitlab (Inc),DC=gitlab,DC=com
+  ```
+
+  These characters must be escaped as documented in
+  [RFC 4515](https://tools.ietf.org/search/rfc4515).
+
+- Escape commas with `\2C`. For example:
+
+  ```plaintext
+  OU=GitLab\2C Inc,DC=gitlab,DC=com
+  ```
+
+- Escape open and close brackets with `\28` and `\29`, respectively. For example:
+
+  ```plaintext
+  OU=Gitlab \28Inc\29,DC=gitlab,DC=com
+  ```
+
+### Enabling LDAP username lowercase **(CORE ONLY)**
+
+Some LDAP servers, depending on their configurations, can return uppercase usernames.
+This can lead to several confusing issues such as creating links or namespaces with uppercase names.
+
+GitLab can automatically lowercase usernames provided by the LDAP server by enabling
+the configuration option `lowercase_usernames`. By default, this configuration option is `false`.
+
+**Omnibus configuration**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['ldap_servers'] = {
+   'main' => {
+     # snip...
+     'lowercase_usernames' => true
+     }
+   }
+   ```
+
+1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+
+**Source configuration**
+
+1. Edit `config/gitlab.yaml`:
+
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           lowercase_usernames: true
+   ```
+
+1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
+
+### Disable LDAP web sign in **(CORE ONLY)**
+
+It can be useful to prevent using LDAP credentials through the web UI when
+an alternative such as SAML is preferred. This allows LDAP to be used for group
+sync, while also allowing your SAML identity provider to handle additional
+checks like custom 2FA.
+
+When LDAP web sign in is disabled, users will not see a **LDAP** tab on the sign in page.
+This does not disable [using LDAP credentials for Git access](#git-password-authentication-core-only).
+
+**Omnibus configuration**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['prevent_ldap_sign_in'] = true
+   ```
+
+1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+
+**Source configuration**
+
+1. Edit `config/gitlab.yaml`:
+
+   ```yaml
+   production:
+     ldap:
+       prevent_ldap_sign_in: true
+   ```
+
+1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
+
+## Encryption **(CORE ONLY)**
+
+### TLS Server Authentication
+
+There are two encryption methods, `simple_tls` and `start_tls`.
+
+For either encryption method, if setting `verify_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.
+
+### Limitations
+
+#### TLS Client Authentication
+
+Not implemented by `Net::LDAP`.
+
+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.
+
+## Multiple LDAP servers **(STARTER ONLY)**
+
+With GitLab Enterprise Edition Starter, you can configure multiple LDAP servers
+that your GitLab instance will connect to.
+
+To add another LDAP server:
+
+1. Duplicate the settings under [the main configuration](#configuration-core-only).
+1. Edit them to match the additional LDAP server.
+
+Be sure to choose a different provider ID made of letters a-z and numbers 0-9.
+This ID will be stored in the database so that GitLab can remember which LDAP
+server a user belongs to.
+
+![Multiple LDAP Servers Login](img/multi_login.gif)
+
+Based on the example illustrated on the image above,
+our `gitlab.rb` configuration would look like:
+
+```ruby
+gitlab_rails['ldap_enabled'] = true
+gitlab_rails['ldap_servers'] = {
+'main' => {
+  'label' => 'GitLab AD',
+  'host' =>  'ad.example.org',
+  'port' => 636,
+  ...
+  },
+
+'secondary' => {
+  'label' => 'GitLab Secondary AD',
+  'host' =>  'ad-secondary.example.net',
+  'port' => 636,
+  ...
+  },
+
+'tertiary' => {
+  'label' => 'GitLab Tertiary AD',
+  'host' =>  'ad-tertiary.example.net',
+  'port' => 636,
+  ...
+  }
+  
+}
+```
+
+NOTE: **Note:**
+Any number of LDAP servers can be configured. However, make sure to use a unique naming convention for the `label` section of each entry as this will be the display name of the tab shown on the sign-in page.
+
+## User sync **(STARTER ONLY)**
+
+Once per day, GitLab runs a worker to check and update GitLab
+users against LDAP.
+
+The process executes the following access checks:
+
+- Ensure the user is still present in LDAP.
+- If the LDAP server is Active Directory, ensure the user is active (not
+  blocked/disabled state). This will only be checked if
+  `active_directory: true` is set in the LDAP configuration.
+
+NOTE: **Note:**
+In Active Directory, a user is marked as disabled/blocked if the user
+account control attribute (`userAccountControl:1.2.840.113556.1.4.803`)
+has bit 2 set. See <https://ctovswild.com/2009/09/03/bitmask-searches-in-ldap/>
+for more information.
+
+The user will be set to `ldap_blocked` state in GitLab if the above conditions
+fail. This means the user will not be able to login or push/pull code.
+
+The process will also update the following user information:
+
+- Email address.
+- If `sync_ssh_keys` is set, SSH public keys.
+- If Kerberos is enabled, Kerberos identity.
+
+NOTE: **Note:**
+The LDAP sync process updates existing users while new users are created on first sign in.
+
+### Adjusting LDAP user sync schedule **(STARTER ONLY)**
+
+NOTE: **Note:**
+These are cron formatted values. You can use a crontab generator to create
+these values, for example <http://www.crontabgenerator.com/>.
+
+By default, GitLab will run a worker once per day at 01:30 a.m. server time to
+check and update GitLab users against LDAP.
+
+You can manually configure LDAP user sync times by setting the
+following configuration values. The example below shows how to set LDAP user
+sync to run once every 12 hours at the top of the hour.
+
+**Omnibus installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"
+   ```
+
+1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+
+**Source installations**
+
+1. Edit `config/gitlab.yaml`:
+
+   ```yaml
+   cron_jobs:
+     ldap_sync_worker_cron:
+       "0 */12 * * *"
+   ```
+
+1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
+
+## Group Sync **(STARTER ONLY)**
+
+If your LDAP supports the `memberof` property, when the user signs in for the
+first time GitLab will trigger a sync for groups the user should be a member of.
+That way they don't need to wait for the hourly sync to be granted
+access to their groups and projects.
+
+A group sync process will run every hour on the hour, and `group_base` must be set
+in LDAP configuration for LDAP synchronizations based on group CN to work. This allows
+GitLab group membership to be automatically updated based on LDAP group members.
+
+The `group_base` configuration should be a base LDAP 'container', such as an
+'organization' or 'organizational unit', that contains LDAP groups that should
+be available to GitLab. For example, `group_base` could be
+`ou=groups,dc=example,dc=com`. In the config file it will look like the
+following.
+
+**Omnibus configuration**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['ldap_servers'] = {
+   'main' => {
+     # snip...
+     'group_base' => 'ou=groups,dc=example,dc=com',
+     }
+   }
+   ```
+
+1. [Apply your changes to GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure).
+
+**Source configuration**
+
+1. Edit `/home/git/gitlab/config/gitlab.yml`:
+
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           group_base: ou=groups,dc=example,dc=com
+   ```
+
+1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
+
+To take advantage of group sync, group owners or maintainers will need to [create one
+or more LDAP group links](#adding-group-links-starter-only).
+
+### Adding group links **(STARTER ONLY)**
+
+For information on adding group links via CNs and filters, refer to [the GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap).
+
+### Administrator sync **(STARTER ONLY)**
+
+As an extension of group sync, you can automatically manage your global GitLab
+administrators. Specify a group CN for `admin_group` and all members of the
+LDAP group will be given administrator privileges. The configuration will look
+like the following.
+
+NOTE: **Note:**
+Administrators will not be synced unless `group_base` is also
+specified alongside `admin_group`. Also, only specify the CN of the admin
+group, as opposed to the full DN.
+
+**Omnibus configuration**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['ldap_servers'] = {
+   'main' => {
+     # snip...
+     'group_base' => 'ou=groups,dc=example,dc=com',
+     'admin_group' => 'my_admin_group',
+     }
+   }
+   ```
+
+1. [Apply your changes to GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure).
+
+**Source configuration**
+
+1. Edit `/home/git/gitlab/config/gitlab.yml`:
+
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           group_base: ou=groups,dc=example,dc=com
+           admin_group: my_admin_group
+   ```
+
+1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
+
+### Global group memberships lock **(STARTER ONLY)**
+
+"Lock memberships to LDAP synchronization" setting allows instance administrators
+to lock down user abilities to invite new members to a group.
+
+When enabled, the following applies:
+
+- Only administrator can manage memberships of any group including access levels.
+- Users are not allowed to share project with other groups or invite members to
+  a project created in a group.
+
+### Adjusting LDAP group sync schedule **(STARTER ONLY)**
+
+NOTE: **Note:**
+These are cron formatted values. You can use a crontab generator to create
+these values, for example [Crontab Generator](http://www.crontabgenerator.com/).
+
+By default, GitLab runs a group sync process every hour, on the hour.
+
+CAUTION: **Important:**
+It's recommended that you do not start the sync process too frequently as this
+could lead to multiple syncs running concurrently. This is primarily a concern
+for installations with a large number of LDAP users. Please review the
+[LDAP group sync benchmark metrics](#benchmarks) to see how
+your installation compares before proceeding.
+
+You can manually configure LDAP group sync times by setting the
+following configuration values. The example below shows how to set group
+sync to run once every 2 hours at the top of the hour.
+
+**Omnibus installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *"
+   ```
+
+1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+
+**Source installations**
+
+1. Edit `config/gitlab.yaml`:
+
+   ```yaml
+   cron_jobs:
+     ldap_group_sync_worker_cron:
+         "*/30 * * * *"
+   ```
+
+1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
+
+### External groups **(STARTER ONLY)**
+
+Using the `external_groups` setting will allow you to mark all users belonging
+to these groups as [external users](../../../user/permissions.md#external-users-core-only).
+Group membership is checked periodically through the `LdapGroupSync` background
+task.
+
+**Omnibus configuration**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['ldap_servers'] = {
+   'main' => {
+     # snip...
+     'external_groups' => ['interns', 'contractors'],
+     }
+   }
+   ```
+
+1. [Apply your changes to GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure).
+
+**Source configuration**
+
+1. Edit `config/gitlab.yaml`:
+
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           external_groups: ['interns', 'contractors']
+   ```
+
+1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
+
+### Group sync technical details
+
+There is a lot going on with group sync 'under the hood'. This section
+outlines what LDAP queries are executed and what behavior you can expect
+from group sync.
+
+Group member access will be downgraded from a higher level if their LDAP group
+membership changes. For example, if a user has 'Owner' rights in a group and the
+next group sync reveals they should only have 'Developer' privileges, their
+access will be adjusted accordingly. The only exception is if the user is the
+*last* owner in a group. Groups need at least one owner to fulfill
+administrative duties.
+
+#### Supported LDAP group types/attributes
+
+GitLab supports LDAP groups that use member attributes:
+
+- `member`
+- `submember`
+- `uniquemember`
+- `memberof`
+- `memberuid`.
+
+This means group sync supports, at least, LDAP groups with the following object classes:
+`groupOfNames`, `posixGroup`, and `groupOfUniqueNames`.
+
+Other object classes should work fine as long as members
+are defined as one of the mentioned attributes. This also means GitLab supports
+Microsoft Active Directory, Apple Open Directory, Open LDAP, and 389 Server.
+Other LDAP servers should work, too.
+
+Active Directory also supports nested groups. Group sync will recursively
+resolve membership if `active_directory: true` is set in the configuration file.
+
+NOTE: **Note:**
+Nested group memberships are resolved only if the nested group
+is found within the configured `group_base`. For example, if GitLab sees a
+nested group with DN `cn=nested_group,ou=special_groups,dc=example,dc=com` but
+the configured `group_base` is `ou=groups,dc=example,dc=com`, `cn=nested_group`
+is ignored.
+
+#### Queries
+
+- Each LDAP group is queried a maximum of one time with base `group_base` and
+  filter `(cn=<cn_from_group_link>)`.
+- If the LDAP group has the `memberuid` attribute, GitLab will execute another
+  LDAP query per member to obtain each user's full DN. These queries are
+  executed with base `base`, scope 'base object', and a filter depending on
+  whether `user_filter` is set. Filter may be `(uid=<uid_from_group>)` or a
+  joining of `user_filter`.
+
+#### Benchmarks
+
+Group sync was written to be as performant as possible. Data is cached, database
+queries are optimized, and LDAP queries are minimized. The last benchmark run
+revealed the following metrics:
+
+For 20000 LDAP users, 11000 LDAP groups and 1000 GitLab groups with 10
+LDAP group links each:
+
+- Initial sync (no existing members assigned in GitLab) took 1.8 hours
+- Subsequent syncs (checking membership, no writes) took 15 minutes
+
+These metrics are meant to provide a baseline and performance may vary based on
+any number of factors. This was a pretty extreme benchmark and most instances will
+not have near this many users or groups. Disk speed, database performance,
+network and LDAP server response time will affect these metrics.
+
+## Troubleshooting
+
+Please see our [administrator guide to troubleshooting LDAP](ldap-troubleshooting.md).
diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md
new file mode 100644
index 00000000000..909802b5dec
--- /dev/null
+++ b/doc/administration/auth/ldap/ldap-troubleshooting.md
@@ -0,0 +1,678 @@
+---
+type: reference
+stage: Manage
+group: Access
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# LDAP Troubleshooting for Administrators
+
+## Common Problems & Workflows
+
+### Connection
+
+#### Connection refused
+
+If you are getting `Connection Refused` errors when trying to connect to the
+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`.
+
+#### Connection times out
+
+If GitLab cannot reach your LDAP endpoint, you will see a message like this:
+
+```plaintext
+Could not authenticate you from Ldapmain because "Connection timed out - user specified timeout".
+```
+
+If your configured LDAP provider and/or endpoint is offline or otherwise
+unreachable by GitLab, no LDAP user will be able to authenticate and log in.
+GitLab does not cache or store credentials for LDAP users to provide authentication
+during an LDAP outage.
+
+Contact your LDAP provider or administrator if you are seeing this error.
+
+#### Referral error
+
+If you see `LDAP search error: Referral` in the logs, or when troubleshooting
+LDAP Group Sync, this error may indicate a configuration problem. The LDAP
+configuration `/etc/gitlab/gitlab.rb` (Omnibus) or `config/gitlab.yml` (source)
+is in YAML format and is sensitive to indentation. Check that `group_base` and
+`admin_group` configuration keys are indented 2 spaces past the server
+identifier. The default identifier is `main` and an example snippet looks like
+the following:
+
+```yaml
+main: # 'main' is the GitLab 'provider ID' of this LDAP server
+  label: 'LDAP'
+  host: 'ldap.example.com'
+  ...
+  group_base: 'cn=my_group,ou=groups,dc=example,dc=com'
+  admin_group: 'my_admin_group'
+```
+
+#### Query LDAP **(STARTER ONLY)**
+
+The following allows you to perform a search in LDAP using the rails console.
+Depending on what you're trying to do, it may make more sense to query [a
+user](#query-a-user-in-ldap) or [a group](#query-a-group-in-ldap-starter-only) directly, or
+even [use `ldapsearch`](#ldapsearch) instead.
+
+```ruby
+adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain')
+options = {
+    # :base is required
+    # use .base or .group_base
+    base: adapter.config.group_base,
+
+    # :filter is optional
+    # 'cn' looks for all "cn"s under :base
+    # '*' is the search string - here, it's a wildcard
+    filter: Net::Ldap::Filter.eq('cn', '*'),
+
+    # :attributes is optional
+    # the attributes we want to get returned
+    attributes: %w(dn cn memberuid member submember uniquemember memberof)
+}
+adapter.ldap_search(options)
+```
+
+For examples of how this is run,
+[review the `Adapter` module](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/ee/gitlab/auth/ldap/adapter.rb).
+
+### User logins
+
+#### No users are found
+
+If [you've confirmed](#ldap-check) that a connection to LDAP can be
+established but GitLab doesn't show you LDAP users in the output, one of the
+following is most likely true:
+
+- The `bind_dn` user doesn't have enough permissions to traverse the user tree.
+- The user(s) don't fall under the [configured `base`](index.md#configuration-core-only).
+- The [configured `user_filter`](index.md#set-up-ldap-user-filter-core-only) blocks access to the user(s).
+
+In this case, you con confirm which of the above is true using
+[ldapsearch](#ldapsearch) with the existing LDAP configuration in your
+`/etc/gitlab/gitlab.rb`.
+
+#### User(s) cannot login
+
+A user can have trouble logging in for any number of reasons. To get started,
+here are some questions to ask yourself:
+
+- Does the user fall under the [configured `base`](index.md#configuration-core-only) in
+  LDAP? The user must fall under this `base` to login.
+- Does the user pass through the [configured `user_filter`](index.md#set-up-ldap-user-filter-core-only)?
+  If one is not configured, this question can be ignored. If it is, then the
+  user must also pass through this filter to be allowed to login.
+  - Refer to our docs on [debugging the `user_filter`](#debug-ldap-user-filter).
+
+If the above are both okay, the next place to look for the problem is
+the logs themselves while reproducing the issue.
+
+- Ask the user to login and let it fail.
+- [Look through the output](#gitlab-logs) for any errors or other
+  messages about the login. You may see one of the other error messages on
+  this page, in which case that section can help resolve the issue.
+
+If the logs don't lead to the root of the problem, use the
+[rails console](#rails-console) to [query this user](#query-a-user-in-ldap)
+to see if GitLab can read this user on the LDAP server.
+
+It can also be helpful to
+[debug a user sync](#sync-all-users-starter-only) to
+investigate further.
+
+#### Invalid credentials on login
+
+If that the login credentials used are accurate on LDAP, ensure the following
+are true for the user in question:
+
+- Make sure the user you are binding with has enough permissions to read the user's
+  tree and traverse it.
+- Check that the `user_filter` is not blocking otherwise valid users.
+- Run [an LDAP check command](#ldap-check) to make sure that the LDAP settings
+  are correct and [GitLab can see your users](#no-users-are-found).
+
+#### Email has already been taken
+
+A user tries to login with the correct LDAP credentials, is denied access,
+and the [production.log](../../logs.md#productionlog) shows an error that looks like this:
+
+```plaintext
+(LDAP) Error saving user <USER DN> (email@example.com): ["Email has already been taken"]
+```
+
+This error is referring to the email address in LDAP, `email@example.com`. Email
+addresses must be unique in GitLab and LDAP links to a user's primary email (as opposed
+to any of their possibly-numerous secondary emails). Another user (or even the
+same user) has the email `email@example.com` set as a secondary email, which
+is throwing this error.
+
+We can check where this conflicting email address is coming from using the
+[rails console](#rails-console). Once in the console, run the following:
+
+```ruby
+# This searches for an email among the primary AND secondary emails
+user = User.find_by_any_email('email@example.com')
+user.username
+```
+
+This will show you which user has this email address. One of two steps will
+have to be taken here:
+
+- To create a new GitLab user/username for this user when logging in with LDAP,
+  remove the secondary email to remove the conflict.
+- To use an existing GitLab user/username for this user to use with LDAP,
+  remove this email as a secondary email and make it a primary one so GitLab
+  will associate this profile to the LDAP identity.
+
+The user can do either of these steps [in their
+profile](../../../user/profile/index.md#user-profile) or an admin can do it.
+
+#### Debug LDAP user filter
+
+[`ldapsearch`](#ldapsearch) allows you to test your configured
+[user filter](index.md#set-up-ldap-user-filter-core-only)
+to confirm that it returns the users you expect it to return.
+
+```shell
+ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt  -b "$base" "$user_filter" sAMAccountName
+```
+
+- Variables beginning with a `$` refer to a variable from the LDAP section of
+  your configuration file.
+- Replace `ldaps://` with `ldap://` if you are using the plain authentication method.
+  Port `389` is the default `ldap://` port and `636` is the default `ldaps://`
+  port.
+- We are assuming the password for the `bind_dn` user is in `bind_dn_password.txt`.
+
+#### Sync all users **(STARTER ONLY)**
+
+The output from a manual [user sync](index.md#user-sync-starter-only) can show you what happens when
+GitLab tries to sync its users against LDAP. Enter the [rails console](#rails-console)
+and then run:
+
+```ruby
+Rails.logger.level = Logger::DEBUG
+
+LdapSyncWorker.new.perform
+```
+
+Next, [learn how to read the
+output](#example-console-output-after-a-user-sync-starter-only).
+
+##### Example console output after a user sync **(STARTER ONLY)**
+
+The output from a [manual user sync](#sync-all-users-starter-only) will be very verbose, and a
+single user's successful sync can look like this:
+
+```shell
+Syncing user John, email@example.com
+  Identity Load (0.9ms)  SELECT  "identities".* FROM "identities" WHERE "identities"."user_id" = 20 AND (provider LIKE 'ldap%') LIMIT 1
+Instantiating Gitlab::Auth::Ldap::Person with LDIF:
+dn: cn=John Smith,ou=people,dc=example,dc=com
+cn: John Smith
+mail: email@example.com
+memberof: cn=admin_staff,ou=people,dc=example,dc=com
+uid: John
+
+  UserSyncedAttributesMetadata Load (0.9ms)  SELECT  "user_synced_attributes_metadata".* FROM "user_synced_attributes_metadata" WHERE "user_synced_attributes_metadata"."user_id" = 20 LIMIT 1
+   (0.3ms)  BEGIN
+  Namespace Load (1.0ms)  SELECT  "namespaces".* FROM "namespaces" WHERE "namespaces"."owner_id" = 20 AND "namespaces"."type" IS NULL LIMIT 1
+  Route Load (0.8ms)  SELECT  "routes".* FROM "routes" WHERE "routes"."source_id" = 27 AND "routes"."source_type" = 'Namespace' LIMIT 1
+  Ci::Runner Load (1.1ms)  SELECT "ci_runners".* FROM "ci_runners" INNER JOIN "ci_runner_namespaces" ON "ci_runners"."id" = "ci_runner_namespaces"."runner_id" WHERE "ci_runner_namespaces"."namespace_id" = 27
+   (0.7ms)  COMMIT
+   (0.4ms)  BEGIN
+  Route Load (0.8ms)  SELECT "routes".* FROM "routes" WHERE (LOWER("routes"."path") = LOWER('John'))
+  Namespace Load (1.0ms)  SELECT  "namespaces".* FROM "namespaces" WHERE "namespaces"."id" = 27 LIMIT 1
+  Route Exists (0.9ms)  SELECT  1 AS one FROM "routes" WHERE LOWER("routes"."path") = LOWER('John') AND "routes"."id" != 50 LIMIT 1
+  User Update (1.1ms)  UPDATE "users" SET "updated_at" = '2019-10-17 14:40:59.751685', "last_credential_check_at" = '2019-10-17 14:40:59.738714' WHERE "users"."id" = 20
+```
+
+There's a lot here, so let's go over what could be helpful when debugging.
+
+First, GitLab will look for all users that have previously
+logged in with LDAP and iterate on them. Each user's sync will start with
+the following line that contains the user's username and email, as they
+exist in GitLab now:
+
+```shell
+Syncing user John, email@example.com
+```
+
+If you don't find a particular user's GitLab email in the output, then that
+user hasn't logged in with LDAP yet.
+
+Next, GitLab searches its `identities` table for the existing
+link between this user and the configured LDAP provider(s):
+
+```sql
+  Identity Load (0.9ms)  SELECT  "identities".* FROM "identities" WHERE "identities"."user_id" = 20 AND (provider LIKE 'ldap%') LIMIT 1
+```
+
+The identity object will have the DN that GitLab will use to look for the user
+in LDAP. If the DN isn't found, the email is used instead. We can see that
+this user is found in LDAP:
+
+```shell
+Instantiating Gitlab::Auth::Ldap::Person with LDIF:
+dn: cn=John Smith,ou=people,dc=example,dc=com
+cn: John Smith
+mail: email@example.com
+memberof: cn=admin_staff,ou=people,dc=example,dc=com
+uid: John
+```
+
+If the user wasn't found in LDAP with either the DN or email, you may see the
+following message instead:
+
+```shell
+LDAP search error: No Such Object
+```
+
+...in which case the user will be blocked:
+
+```shell
+  User Update (0.4ms)  UPDATE "users" SET "state" = $1, "updated_at" = $2 WHERE "users"."id" = $3  [["state", "ldap_blocked"], ["updated_at", "2019-10-18 15:46:22.902177"], ["id", 20]]
+```
+
+Once the user is found in LDAP the rest of the output will update the GitLab
+database with any changes.
+
+#### Query a user in LDAP
+
+This will test that GitLab can reach out to LDAP and read a particular user.
+It can expose potential errors connecting to and/or querying LDAP
+that may seem to fail silently in the GitLab UI.
+
+```ruby
+Rails.logger.level = Logger::DEBUG
+
+adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain') # If `main` is the LDAP provider
+Gitlab::Auth::Ldap::Person.find_by_uid('<uid>', adapter)
+```
+
+### Group memberships **(STARTER ONLY)**
+
+#### Membership(s) not granted **(STARTER ONLY)**
+
+Sometimes you may think a particular user should be added to a GitLab group via
+LDAP group sync, but for some reason it's not happening. There are several
+things to check to debug the situation.
+
+- Ensure LDAP configuration has a `group_base` specified.
+  [This configuration](index.md#group-sync-starter-only) is required for group sync to work properly.
+- Ensure the correct [LDAP group link is added to the GitLab
+  group](index.md#adding-group-links-starter-only).
+- Check that the user has an LDAP identity:
+  1. Sign in to GitLab as an administrator user.
+  1. Navigate to **Admin area -> Users**.
+  1. Search for the user
+  1. Open the user, by clicking on their name. Do not click 'Edit'.
+  1. Navigate to the **Identities** tab. There should be an LDAP identity with
+     an LDAP DN as the 'Identifier'. If not, this user hasn't logged in with
+     LDAP yet and must do so first.
+- You've waited an hour or [the configured
+  interval](index.md#adjusting-ldap-group-sync-schedule-starter-only) for the group to
+  sync. To speed up the process, either go to the GitLab group **Settings ->
+  Members** and press **Sync now** (sync one group) or [run the group sync Rake
+  task](../../raketasks/ldap.md#run-a-group-sync-starter-only) (sync all groups).
+
+If all of the above looks good, jump in to a little more advanced debugging in
+the rails console.
+
+1. Enter the [rails console](#rails-console).
+1. Choose a GitLab group to test with. This group should have an LDAP group link
+   already configured.
+1. [Enable debug logging, find the above GitLab group, and sync it with LDAP](#sync-one-group-starter-only).
+1. Look through the output of the sync. See [example log
+   output](#example-console-output-after-a-group-sync-starter-only)
+   for how to read the output.
+1. If you still aren't able to see why the user isn't being added, [query the
+   LDAP group directly](#query-a-group-in-ldap-starter-only) to see what members are listed.
+1. Is the user's DN or UID in one of the lists from the above output? One of the DNs or
+   UIDs here should match the 'Identifier' from the LDAP identity checked earlier. If it doesn't,
+   the user does not appear to be in the LDAP group.
+
+#### Admin privileges not granted
+
+When [Administrator sync](index.md#administrator-sync-starter-only) has been configured
+but the configured users aren't granted the correct admin privileges, confirm
+the following are true:
+
+- A [`group_base` is also configured](index.md#group-sync-starter-only).
+- The configured `admin_group` in the `gitlab.rb` is a CN, rather than a DN or an array.
+- This CN falls under the scope of the configured `group_base`.
+- The members of the `admin_group` have already logged into GitLab with their LDAP
+  credentials. GitLab will only grant this admin access to the users whose
+  accounts are already connected to LDAP.
+
+If all the above are true and the users are still not getting access, [run a manual
+group sync](#sync-all-groups-starter-only) in the rails console and [look through the
+output](#example-console-output-after-a-group-sync-starter-only) to see what happens when
+GitLab syncs the `admin_group`.
+
+#### Sync all groups **(STARTER ONLY)**
+
+NOTE: **NOTE:**
+To sync all groups manually when debugging is unnecessary, [use the Rake
+task](../../raketasks/ldap.md#run-a-group-sync-starter-only) instead.
+
+The output from a manual [group sync](index.md#group-sync-starter-only) can show you what happens
+when GitLab syncs its LDAP group memberships against LDAP.
+
+```ruby
+Rails.logger.level = Logger::DEBUG
+
+LdapAllGroupsSyncWorker.new.perform
+```
+
+Next, [learn how to read the
+output](#example-console-output-after-a-group-sync-starter-only).
+
+##### Example console output after a group sync **(STARTER ONLY)**
+
+Like the output from the user sync, the output from the [manual group
+sync](#sync-all-groups-starter-only) will also be very verbose. However, it contains lots
+of helpful information.
+
+Indicates the point where syncing actually begins:
+
+```shell
+Started syncing 'ldapmain' provider for 'my_group' group
+```
+
+The following entry shows an array of all user DNs GitLab sees in the LDAP server.
+Note that these are the users for a single LDAP group, not a GitLab group. If
+you have multiple LDAP groups linked to this GitLab group, you will see multiple
+log entries like this - one for each LDAP group. If you don't see an LDAP user
+DN in this log entry, LDAP is not returning the user when we do the lookup.
+Verify the user is actually in the LDAP group.
+
+```shell
+Members in 'ldap_group_1' LDAP group: ["uid=john0,ou=people,dc=example,dc=com",
+"uid=mary0,ou=people,dc=example,dc=com", "uid=john1,ou=people,dc=example,dc=com",
+"uid=mary1,ou=people,dc=example,dc=com", "uid=john2,ou=people,dc=example,dc=com",
+"uid=mary2,ou=people,dc=example,dc=com", "uid=john3,ou=people,dc=example,dc=com",
+"uid=mary3,ou=people,dc=example,dc=com", "uid=john4,ou=people,dc=example,dc=com",
+"uid=mary4,ou=people,dc=example,dc=com"]
+```
+
+Shortly after each of the above entries, you will see a hash of resolved member
+access levels. This hash represents all user DNs GitLab thinks should have
+access to this group, and at which access level (role). This hash is additive,
+and more DNs may be added, or existing entries modified, based on additional
+LDAP group lookups. The very last occurrence of this entry should indicate
+exactly which users GitLab believes should be added to the group.
+
+NOTE: **Note:**
+10 is 'Guest', 20 is 'Reporter', 30 is 'Developer', 40 is 'Maintainer'
+and 50 is 'Owner'.
+
+```shell
+Resolved 'my_group' group member access: {"uid=john0,ou=people,dc=example,dc=com"=>30,
+"uid=mary0,ou=people,dc=example,dc=com"=>30, "uid=john1,ou=people,dc=example,dc=com"=>30,
+"uid=mary1,ou=people,dc=example,dc=com"=>30, "uid=john2,ou=people,dc=example,dc=com"=>30,
+"uid=mary2,ou=people,dc=example,dc=com"=>30, "uid=john3,ou=people,dc=example,dc=com"=>30,
+"uid=mary3,ou=people,dc=example,dc=com"=>30, "uid=john4,ou=people,dc=example,dc=com"=>30,
+"uid=mary4,ou=people,dc=example,dc=com"=>30}
+```
+
+It's not uncommon to see warnings like the following. These indicate that GitLab
+would have added the user to a group, but the user could not be found in GitLab.
+Usually this is not a cause for concern.
+
+If you think a particular user should already exist in GitLab, but you're seeing
+this entry, it could be due to a mismatched DN stored in GitLab. See
+[User DN and/or email have changed](#user-dn-orand-email-have-changed) to update the user's LDAP identity.
+
+```shell
+User with DN `uid=john0,ou=people,dc=example,dc=com` should have access
+to 'my_group' group but there is no user in GitLab with that
+identity. Membership will be updated once the user signs in for
+the first time.
+```
+
+Finally, the following entry says syncing has finished for this group:
+
+```shell
+Finished syncing all providers for 'my_group' group
+```
+
+Once all the configured group links have been synchronized, GitLab will look
+for any Administrators or External users to sync:
+
+```shell
+Syncing admin users for 'ldapmain' provider
+```
+
+The output will look similar to what happens with a single group, and then
+this line will indicate the sync is finished:
+
+```shell
+Finished syncing admin users for 'ldapmain' provider
+```
+
+If [admin sync](index.md#administrator-sync-starter-only) is not configured, you'll see a message
+stating as such:
+
+```shell
+No `admin_group` configured for 'ldapmain' provider. Skipping
+```
+
+#### Sync one group **(STARTER ONLY)**
+
+[Syncing all groups](#sync-all-groups-starter-only) can produce a lot of noise in the output, which can be
+distracting when you're only interested in troubleshooting the memberships of
+a single GitLab group. In that case, here's how you can just sync this group
+and see its debug output:
+
+```ruby
+Rails.logger.level = Logger::DEBUG
+
+# Find the GitLab group.
+# If the output is `nil`, the group could not be found.
+# If a bunch of group attributes are in the output, your group was found successfully.
+group = Group.find_by(name: 'my_gitlab_group')
+
+# Sync this group against LDAP
+EE::Gitlab::Auth::Ldap::Sync::Group.execute_all_providers(group)
+```
+
+The output will be similar to
+[that you'd get from syncing all groups](#example-console-output-after-a-group-sync-starter-only).
+
+#### Query a group in LDAP **(STARTER ONLY)**
+
+When you'd like to confirm that GitLab can read a LDAP group and see all its members,
+you can run the following:
+
+```ruby
+# Find the adapter and the group itself
+adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain') # If `main` is the LDAP provider
+ldap_group = EE::Gitlab::Auth::Ldap::Group.find_by_cn('group_cn_here', adapter)
+
+# Find the members of the LDAP group
+ldap_group.member_dns
+ldap_group.member_uids
+```
+
+### User DN or/and email have changed
+
+When an LDAP user is created in GitLab, their LDAP DN is stored for later reference.
+
+If GitLab cannot find a user by their DN, it will fall back
+to finding the user by their email. If the lookup is successful, GitLab will
+update the stored DN to the new value so both values will now match what's in
+LDAP.
+
+If the email has changed and the DN has not, GitLab will find the user with
+the DN and update its own record of the user's email to match the one in LDAP.
+
+However, if the primary email _and_ the DN change in LDAP, then GitLab will
+have no way of identifying the correct LDAP record of the user and, as a
+result, the user will be blocked. To rectify this, the user's existing
+profile will have to be updated with at least one of the new values (primary
+email or DN) so the LDAP record can be found.
+
+The following script will update the emails for all provided users so they
+won't be blocked or unable to access their accounts.
+
+>**NOTE**: The following script will require that any new accounts with the new
+email address are removed first. This is because emails have to be unique in GitLab.
+
+Go to the [rails console](#rails-console) and then run:
+
+```ruby
+# Each entry will have to include the old username and the new email
+emails = {
+  'ORIGINAL_USERNAME' => 'NEW_EMAIL_ADDRESS',
+  ...
+}
+
+emails.each do |username, email|
+  user = User.find_by_username(username)
+  user.email = email
+  user.skip_reconfirmation!
+  user.save!
+end
+```
+
+You can then [run a UserSync](#sync-all-users-starter-only) **(STARTER ONLY)** to sync the latest DN
+for each of these users.
+
+## Debugging Tools
+
+### LDAP check
+
+The [Rake task to check LDAP](../../raketasks/ldap.md#check) is a valuable tool
+to help determine whether GitLab can successfully establish a connection to
+LDAP and can get so far as to even read users.
+
+If a connection can't be established, it is likely either because of a problem
+with your configuration or a firewall blocking the connection.
+
+- Ensure you don't have a firewall blocking the
+connection, and that the LDAP server is accessible to the GitLab host.
+- Look for an error message in the Rake check output, which may lead to your LDAP configuration to
+confirm that the configuration values (specifically `host`, `port`, `bind_dn`, and
+`password`) are correct.
+- Look for [errors](#connection) in [the logs](#gitlab-logs) to further debug connection failures.
+
+If GitLab can successfully connect to LDAP but doesn't return any
+users, [see what to do when no users are found](#no-users-are-found).
+
+### GitLab logs
+
+If a user account is blocked or unblocked due to the LDAP configuration, a
+message will be [logged to `application.log`](../../logs.md#applicationlog).
+
+If there is an unexpected error during an LDAP lookup (configuration error,
+timeout), the login is rejected and a message will be [logged to
+`production.log`](../../logs.md#productionlog).
+
+### ldapsearch
+
+`ldapsearch` is a utility that will allow you to query your LDAP server. You can
+use it to test your LDAP settings and ensure that the settings you're using
+will get you the results you expect.
+
+When using `ldapsearch`, be sure to use the same settings you've already
+specified in your `gitlab.rb` configuration so you can confirm what happens
+when those exact settings are used.
+
+Running this command on the GitLab host will also help confirm that there's no
+obstruction between the GitLab host and LDAP.
+
+For example, consider the following GitLab configuration:
+
+```shell
+gitlab_rails['ldap_servers'] = YAML.load <<-'EOS' # remember to close this block with 'EOS' below
+   main: # 'main' is the GitLab 'provider ID' of this LDAP server
+     label: 'LDAP'
+     host: '127.0.0.1'
+     port: 389
+     uid: 'uid'
+     encryption: 'plain'
+     bind_dn: 'cn=admin,dc=ldap-testing,dc=example,dc=com'
+     password: 'Password1'
+     active_directory: true
+     allow_username_or_email_login: false
+     block_auto_created_users: false
+     base: 'dc=ldap-testing,dc=example,dc=com'
+     user_filter: ''
+     attributes:
+       username: ['uid', 'userid', 'sAMAccountName']
+       email:    ['mail', 'email', 'userPrincipalName']
+       name:       'cn'
+       first_name: 'givenName'
+       last_name:  'sn'
+     group_base: 'ou=groups,dc=ldap-testing,dc=example,dc=com'
+     admin_group: 'gitlab_admin'
+EOS
+```
+
+You would run the following `ldapsearch` to find the `bind_dn` user:
+
+```shell
+ldapsearch -D "cn=admin,dc=ldap-testing,dc=example,dc=com" \
+  -w Password1 \
+  -p 389 \
+  -h 127.0.0.1 \
+  -b "dc=ldap-testing,dc=example,dc=com"
+```
+
+Note that the `bind_dn`, `password`, `port`, `host`, and `base` are all
+identical to what's configured in the `gitlab.rb`.
+
+Please see [the official
+`ldapsearch` documentation](https://linux.die.net/man/1/ldapsearch) for more.
+
+### Using **AdFind** (Windows)
+
+You can use the [`AdFind`](https://social.technet.microsoft.com/wiki/contents/articles/7535.adfind-command-examples.aspx) utility (on Windows based systems) to test that your LDAP server is accessible and authentication is working correctly. This is a freeware utility built by [Joe Richards](http://www.joeware.net/freetools/tools/adfind/index.htm).
+
+**Return all objects**
+
+You can use the filter `objectclass=*` to return all directory objects.
+
+```shell
+adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -up Password1 -b "OU=GitLab INT,DC=GitLab,DC=org" -f (objectClass=*)
+```
+
+**Return single object using filter**
+
+You can also retrieve a single object by **specifying** the object name or full **DN**. In this example we specify the object name only `CN=Leroy Fox`.
+
+```shell
+adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -up Password1 -b "OU=GitLab INT,DC=GitLab,DC=org" -f (&(objectcategory=person)(CN=Leroy Fox))”
+```
+
+### Rails console
+
+CAUTION: **CAUTION:**
+Please note that it is very easy to create, read, modify, and destroy data on the
+rails console, so please be sure to run commands exactly as listed.
+
+The rails console is a valuable tool to help debug LDAP problems. It allows you to
+directly interact with the application by running commands and seeing how GitLab
+responds to them.
+
+Please refer to [this guide](../../troubleshooting/debug.md#starting-a-rails-console-session)
+for instructions on how to use the rails console.
+
+#### Enable debug output
+
+This will provide debug output that will be useful to see
+what GitLab is doing and with what. This value is not persisted, and will only
+be enabled for this session in the rails console.
+
+To enable debug output in the rails console, [enter the rails
+console](#rails-console) and run:
+
+```ruby
+Rails.logger.level = Logger::DEBUG
+```