diff options
Diffstat (limited to 'doc/raketasks/user_management.md')
| -rw-r--r-- | doc/raketasks/user_management.md | 117 |
1 files changed, 64 insertions, 53 deletions
diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md index ffb1baa0b6e..61e30f9ddb1 100644 --- a/doc/raketasks/user_management.md +++ b/doc/raketasks/user_management.md @@ -1,7 +1,11 @@ -# User management +# User management **(CORE ONLY)** + +GitLab provides Rake tasks for user management. ## Add user as a developer to all projects +To add a user as a developer to all projects, run: + ```shell # omnibus-gitlab sudo gitlab-rake gitlab:import:user_to_projects[username@domain.tld] @@ -12,9 +16,7 @@ bundle exec rake gitlab:import:user_to_projects[username@domain.tld] RAILS_ENV=p ## Add all users to all projects -Notes: - -- admin users are added as maintainers +To add all users to all projects, run: ```shell # omnibus-gitlab @@ -24,8 +26,13 @@ sudo gitlab-rake gitlab:import:all_users_to_all_projects bundle exec rake gitlab:import:all_users_to_all_projects RAILS_ENV=production ``` +NOTE: **Note:** +Admin users are added as maintainers. + ## Add user as a developer to all groups +To add a user as a developer to all groups, run: + ```shell # omnibus-gitlab sudo gitlab-rake gitlab:import:user_to_groups[username@domain.tld] @@ -36,9 +43,7 @@ bundle exec rake gitlab:import:user_to_groups[username@domain.tld] RAILS_ENV=pro ## Add all users to all groups -Notes: - -- admin users are added as owners so they can add additional users to the group +To add all users to all groups, run: ```shell # omnibus-gitlab @@ -48,19 +53,25 @@ sudo gitlab-rake gitlab:import:all_users_to_all_groups bundle exec rake gitlab:import:all_users_to_all_groups RAILS_ENV=production ``` -## Maintain tight control over the number of active users on your GitLab installation +NOTE: **Note:** +Admin users are added as owners so they can add additional users to the group. + +## Control the number of active users -- Enable this setting to keep new users blocked until they have been cleared by the admin (default: false). +Enable this setting to keep new users blocked until they have been cleared by the administrator. +Defaults to `false`: ```plaintext block_auto_created_users: false ``` -## Disable Two-factor Authentication (2FA) for all users +## Disable two-factor authentication for all users -This task will disable 2FA for all users that have it enabled. This can be +This task disables two-factor authentication (2FA) for all users that have it enabled. This can be useful if GitLab's `config/secrets.yml` file has been lost and users are unable -to login, for example. +to log in, for example. + +To disable two-factor authentication for all users, run: ```shell # omnibus-gitlab @@ -70,65 +81,65 @@ sudo gitlab-rake gitlab:two_factor:disable_for_all_users bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production ``` -## Rotate Two-factor Authentication (2FA) encryption key +## Rotate two-factor authentication encryption key -GitLab stores the secret data enabling 2FA to work in an encrypted database -column. The encryption key for this data is known as `otp_key_base`, and is +GitLab stores the secret data required for two-factor authentication (2FA) in an encrypted +database column. The encryption key for this data is known as `otp_key_base`, and is stored in `config/secrets.yml`. If that file is leaked, but the individual 2FA secrets have not, it's possible to re-encrypt those secrets with a new encryption key. This allows you to change the leaked key without forcing all users to change their 2FA details. -First, look up the old key. This is in the `config/secrets.yml` file, but -**make sure you're working with the production section**. The line you're -interested in will look like this: +To rotate the two-factor authentication encryption key: -```yaml -production: - otp_key_base: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -``` +1. Look up the old key. This is in the `config/secrets.yml` file, but **make sure you're working + with the production section**. The line you're interested in will look like this: -Next, generate a new secret: + ```yaml + production: + otp_key_base: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + ``` -```shell -# omnibus-gitlab -sudo gitlab-rake secret +1. Generate a new secret: -# installation from source -bundle exec rake secret RAILS_ENV=production -``` + ```shell + # omnibus-gitlab + sudo gitlab-rake secret -Now you need to stop the GitLab server, back up the existing secrets file and -update the database: + # installation from source + bundle exec rake secret RAILS_ENV=production + ``` -```shell -# omnibus-gitlab -sudo gitlab-ctl stop -sudo cp config/secrets.yml config/secrets.yml.bak -sudo gitlab-rake gitlab:two_factor:rotate_key:apply filename=backup.csv old_key=<old key> new_key=<new key> +1. Stop the GitLab server, back up the existing secrets file, and update the database: -# installation from source -sudo /etc/init.d/gitlab stop -cp config/secrets.yml config/secrets.yml.bak -bundle exec rake gitlab:two_factor:rotate_key:apply filename=backup.csv old_key=<old key> new_key=<new key> RAILS_ENV=production -``` + ```shell + # omnibus-gitlab + sudo gitlab-ctl stop + sudo cp config/secrets.yml config/secrets.yml.bak + sudo gitlab-rake gitlab:two_factor:rotate_key:apply filename=backup.csv old_key=<old key> new_key=<new key> -The `<old key>` value can be read from `config/secrets.yml`; `<new key>` was -generated earlier. The **encrypted** values for the user 2FA secrets will be -written to the specified `filename` - you can use this to rollback in case of -error. + # installation from source + sudo /etc/init.d/gitlab stop + cp config/secrets.yml config/secrets.yml.bak + bundle exec rake gitlab:two_factor:rotate_key:apply filename=backup.csv old_key=<old key> new_key=<new key> RAILS_ENV=production + ``` -Finally, change `config/secrets.yml` to set `otp_key_base` to `<new key>` and -restart. Again, make sure you're operating in the **production** section. + The `<old key>` value can be read from `config/secrets.yml` (`<new key>` was + generated earlier). The **encrypted** values for the user 2FA secrets will be + written to the specified `filename`. You can use this to rollback in case of + error. -```shell -# omnibus-gitlab -sudo gitlab-ctl start +1. Change `config/secrets.yml` to set `otp_key_base` to `<new key>` and restart. Again, make sure + you're operating in the **production** section. -# installation from source -sudo /etc/init.d/gitlab start -``` + ```shell + # omnibus-gitlab + sudo gitlab-ctl start + + # installation from source + sudo /etc/init.d/gitlab start + ``` If there are any problems (perhaps using the wrong value for `old_key`), you can restore your backup of `config/secrets.yml` and rollback the changes: |