Merge branch 'ldap_maint_task' into 'master'

Add LDAP maintenance task

I've received quite a few support requests where a user has renamed their LDAP server in the configuration file. This causes lots of issues where users are suddenly unable to sign in. It's easy enough to fix through the Rails console, but each time I had to instruct users how to get to the Rails console and what to type. This Rake task takes care of this and updates from old to new provider automatically.

Example: `sudo gitlab-rake gitlab:ldap:rename_provider[ldapmain,ldapcustom]`

cc/ @patricio @balameb Do you think this is useful?

See merge request !2181

3 files changed, 124 insertions, 22 deletions

diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md
index d1d2fed4861..c8b5434c068 100644
--- a/doc/administration/raketasks/check.md
+++ b/doc/administration/raketasks/check.md
@@ -74,24 +74,5 @@ Example output:
 
 The LDAP check Rake task will test the bind_dn and password credentials
 (if configured) and will list a sample of LDAP users. This task is also
-executed as part of the `gitlab:check` task, but can run independently
-using the command below.
-
-**Omnibus Installation**
-
-```
-sudo gitlab-rake gitlab:ldap:check
-```
-
-**Source Installation**
-
-```bash
-sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
-```
-
-By default, the task will return a sample of 100 LDAP users. Change this
-limit by passing a number to the check task:
-
-```bash
-rake gitlab:ldap:check[50]
-```
+executed as part of the `gitlab:check` task, but can run independently.
+See [LDAP Rake Tasks - LDAP Check](ldap.md#check) for details.
diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md
new file mode 100644
index 00000000000..91fc0133d56
--- /dev/null
+++ b/doc/administration/raketasks/ldap.md
@@ -0,0 +1,120 @@
+# LDAP Rake Tasks
+
+## Check
+
+The LDAP check Rake task will test the `bind_dn` and `password` credentials
+(if configured) and will list a sample of LDAP users. This task is also
+executed as part of the `gitlab:check` task, but can run independently
+using the command below.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:ldap:check
+```
+
+**Source Installation**
+
+```bash
+sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
+```
+
+------
+
+By default, the task will return a sample of 100 LDAP users. Change this
+limit by passing a number to the check task:
+
+```bash
+rake gitlab:ldap:check[50]
+```
+
+## Rename a provider
+
+If you change the LDAP server ID in `gitlab.yml` or `gitlab.rb` you will need
+to update all user identities or users will be unable to sign in. Input the
+old and new provider and this task will update all matching identities in the
+database.
+
+`old_provider` and `new_provider` are derived from the prefix `ldap` plus the
+LDAP server ID from the configuration file. For example, in `gitlab.yml` or
+`gitlab.rb` you may see LDAP configuration like this:
+
+```yaml
+main:
+  label: 'LDAP'
+  host: '_your_ldap_server'
+  port: 389
+  uid: 'sAMAccountName'
+  ...
+```
+
+`main` is the LDAP server ID. Together, the unique provider is `ldapmain`.
+
+> **Warning**: If you input an incorrect new provider users will be unable
+to sign in. If this happens, run the task again with the incorrect provider
+as the `old_provider` and the correct provider as the `new_provider`.
+
+**Omnibus Installation**
+
+```bash
+sudo gitlab-rake gitlab:ldap:rename_provider[old_provider,new_provider]
+```
+
+**Source Installation**
+
+```bash
+bundle exec rake gitlab:ldap:rename_provider[old_provider,new_provider] RAILS_ENV=production
+```
+
+### Example
+
+Consider beginning with the default server ID `main` (full provider `ldapmain`).
+If we change `main` to `mycompany`, the `new_provider` is `ldapmycompany`.
+To rename all user identities run the following command:
+
+```bash
+sudo gitlab-rake gitlab:ldap:rename_provider[ldapmain,ldapmycompany]
+```
+
+Example output:
+
+```
+100 users with provider 'ldapmain' will be updated to 'ldapmycompany'.
+If the new provider is incorrect, users will be unable to sign in.
+Do you want to continue (yes/no)? yes
+
+User identities were successfully updated
+```
+
+### Other options
+
+If you do not specify an `old_provider` and `new_provider` you will be prompted
+for them:
+
+**Omnibus Installation**
+
+```bash
+sudo gitlab-rake gitlab:ldap:rename_provider
+```
+
+**Source Installation**
+
+```bash
+bundle exec rake gitlab:ldap:rename_provider RAILS_ENV=production
+```
+
+**Example output:**
+
+```
+What is the old provider? Ex. 'ldapmain': ldapmain
+What is the new provider? Ex. 'ldapcustom': ldapmycompany
+```
+
+------
+
+This tasks also accepts the `force` environment variable which will skip the
+confirmation dialog:
+
+```bash
+sudo gitlab-rake gitlab:ldap:rename_provider[old_provider,new_provider] force=yes
+```
diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md
index a49c43b8ef2..2b81ebc9c59 100644
--- a/doc/raketasks/README.md
+++ b/doc/raketasks/README.md
@@ -4,7 +4,8 @@
 - [Check](check.md)
 - [Cleanup](cleanup.md)
 - [Features](features.md)
-- [Maintenance](maintenance.md) and self-checks
+- [LDAP Maintenance](../administration/raketasks/ldap.md)
+- [General Maintenance](maintenance.md) and self-checks
 - [User management](user_management.md)
 - [Webhooks](web_hooks.md)
 - [Import](import.md) of git repositories in bulk