Add LDAP task to rename a provider

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