Add LDAP task to rename a provider

Sometimes admins will change the LDAP configuration, not realizing
that problems will occur if the user's LDAP identities are not
also updated to use the new provider name. This task will give
admins a single command to run to update identities and will
prevent having to run multiple Rails console queries.

changelogs/unreleased/ldap_maint_task.yml

+---
+title: Add LDAP Rake task to rename a provider
+merge_request: 2181
+author: 

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.

doc/administration/raketasks/ldap.md

+# 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
+```

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

lib/tasks/gitlab/ldap.rake

+namespace :gitlab do
+  namespace :ldap do
+    desc 'GitLab | LDAP | Rename provider'
+    task :rename_provider, [:old_provider, :new_provider] => :environment  do |_, args|
+      old_provider = args[:old_provider] ||
+        prompt('What is the old provider? Ex. \'ldapmain\': '.color(:blue))
+      new_provider = args[:new_provider] ||
+        prompt('What is the new provider ID? Ex. \'ldapcustom\': '.color(:blue))
+      puts '' # Add some separation in the output
+
+      identities = Identity.where(provider: old_provider)
+      identity_count = identities.count
+
+      if identities.empty?
+        puts "Found no user identities with '#{old_provider}' provider."
+        puts 'Please check the provider name and try again.'
+        exit 1
+      end
+
+      plural_id_count = ActionController::Base.helpers.pluralize(identity_count, 'user')
+
+      unless ENV['force'] == 'yes'
+        puts "#{plural_id_count} with provider '#{old_provider}' will be updated to '#{new_provider}'"
+        puts 'If the new provider is incorrect, users will be unable to sign in'
+        ask_to_continue
+        puts ''
+      end
+
+      updated_count = identities.update_all(provider: new_provider)
+
+      if updated_count == identity_count
+        puts 'User identities were successfully updated'.color(:green)
+      else
+        plural_updated_count = ActionController::Base.helpers.pluralize(updated_count, 'user')
+        puts 'Some user identities could not be updated'.color(:red)
+        puts "Successfully updated #{plural_updated_count} out of #{plural_id_count} total"
+      end
+    end
+  end
+end

spec/tasks/gitlab/ldap_rake_spec.rb

+require 'rake_helper'
+
+describe 'gitlab:ldap:rename_provider rake task' do
+  it 'completes without error' do
+    Rake.application.rake_require 'tasks/gitlab/ldap'
+    stub_warn_user_is_not_gitlab
+    ENV['force'] = 'yes'
+
+    create(:identity) # Necessary to prevent `exit 1` from the task.
+
+    run_rake_task('gitlab:ldap:rename_provider', 'ldapmain', 'ldapfoo')
+  end
+end