Commit 8416c08e authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'eread/ctrt-for-reset-user-passwords-topic' into 'master'

CTRT for the Reset user passwords topic

See merge request gitlab-org/gitlab!76515
parents 3f2e7d45 ce9e9513
......@@ -45,6 +45,7 @@ The following Rake tasks are available for use with GitLab:
| [SMTP maintenance](../administration/raketasks/smtp.md) | SMTP-related tasks. |
| [SPDX license list import](spdx.md) | Import a local copy of the [SPDX license list](https://spdx.org/licenses/) for matching [License Compliance policies](../user/compliance/license_compliance/index.md). |
| [Repository storage](../administration/raketasks/storage.md) | List and migrate existing projects and attachments from legacy storage to hashed storage. |
| [Reset user passwords](../security/reset_user_password.md#use-a-rake-task) | Reset user passwords using Rake. |
| [Uploads migrate](../administration/raketasks/uploads/migrate.md) | Migrate uploads between local storage and object storage. |
| [Uploads sanitize](../administration/raketasks/uploads/sanitize.md) | Remove EXIF data from images uploaded to earlier versions of GitLab. |
| [Service Data](../administration/troubleshooting/gitlab_rails_cheat_sheet.md#generate-service-ping) | Generate and troubleshoot [Service Ping](../development/service_ping/index.md). |
......
......@@ -176,3 +176,7 @@ cp config/secrets.yml.bak config/secrets.yml
sudo /etc/init.d/gitlab start
```
## Related topics
- [Reset a user's password](../security/reset_user_password.md#use-a-rake-task).
......@@ -5,121 +5,120 @@ info: To determine the technical writer assigned to the Stage/Group associated w
type: howto
---
# How to reset user password **(FREE SELF)**
# Reset a user's password **(FREE SELF)**
There are a few ways to reset the password of a user.
You can reset user passwords by using a Rake task, a Rails console, or the
[Users API](../api/users.md#user-modification).
## Rake Task
## Prerequisites
To reset a user password, you must be an administrator of a self-managed GitLab instance.
## Use a Rake task
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52347) in GitLab 13.9.
GitLab provides a Rake Task to reset passwords of users using their usernames,
which can be invoked by the following command:
Use the following Rake task to reset a user's password:
```shell
sudo gitlab-rake "gitlab:password:reset"
```
- **For Omnibus installations**
GitLab asks for a username, a password, and a password confirmation. Upon giving
proper values for them, the password of the specified user is updated.
```shell
sudo gitlab-rake "gitlab:password:reset"
```
The Rake task also takes the username as an argument, as shown in the example
below:
- **For installations from source**
```shell
sudo gitlab-rake "gitlab:password:reset[johndoe]"
```
```shell
bundle exec rake "gitlab:password:reset"
```
NOTE:
To reset the default admin password, run this Rake task with the username
`root`, which is the default username of that administrator account.
GitLab requests a username, a password, and confirmation of the password. When complete, the user's password is updated.
## Rails console
The Rake task can take a username as an argument. For example, to reset the password for the user with username
`sidneyjones`:
The Rake task is capable of finding users via their usernames. However, if only
user ID or email ID of the user is known, Rails console can be used to find user
using user ID and then change password of the user manually.
- **For Omnibus installations**
1. [Start a Rails console](../administration/operations/rails_console.md)
```shell
sudo gitlab-rake "gitlab:password:reset[sidneyjones]"
```
1. Find the user either by username, user ID or email ID:
- **For installations from source**
```ruby
user = User.find_by_username 'exampleuser'
```shell
bundle exec rake "gitlab:password:reset[sidneyjones]"
```
#or
## Use a Rails console
user = User.find(123)
If you know the username, user ID, or email address, you can use the Rails console to reset their password:
#or
1. Open a [Rails console](../administration/operations/rails_console.md).
1. Find the user:
user = User.find_by(email: 'user@example.com')
```
- By username:
1. Reset the password
```ruby
user = User.find_by_username 'exampleuser'
```
```ruby
user.password = 'secret_pass'
user.password_confirmation = 'secret_pass'
```
- By user ID:
1. When using this method instead of the [Users API](../api/users.md#user-modification),
GitLab sends an email to the user stating that the user changed their
password. If the password was changed by an administrator, execute the
following command to notify the user by email:
```ruby
user = User.find(123)
```
```ruby
user.send_only_admin_changed_your_password_notification!
- By email address:
```ruby
user = User.find_by(email: 'user@example.com')
```
1. Reset the password:
```ruby
user.password = 'secret_pass'
user.password_confirmation = 'secret_pass'
```
1. Optional. Notify the user that an administrator changed their password:
```ruby
user.send_only_admin_changed_your_password_notification!
```
1. Save the changes:
```ruby
user.save!
```
1. Exit the console, and then try to sign in with your new password.
1. Exit the console:
```ruby
exit
```
NOTE:
You can also reset passwords by using the [Users API](../api/users.md#user-modification).
## Reset the root password
## Password reset does not appear to work
To reset the root password, follow the steps listed previously.
If you can't sign on with the new password, it might be because of the [reconfirmation feature](../user/upgrade_email_bypass.md).
- If the root account name hasn't changed, use the username `root`.
- If the root account name has changed and you don't know the new username,
you might be able to use a Rails console with user ID `1`. In almost all
cases, the first user is the default administrator account.
Try fixing this on the rails console. For example, if your new `root` password isn't working:
## Troubleshooting
1. [Start a Rails console](../administration/operations/rails_console.md).
If the new password doesn't work, it might be [an email confirmation issue](../user/upgrade_email_bypass.md). You can
attempt to fix this issue in a Rails console. For example, if a new `root` password isn't working:
1. Find the user and skip reconfirmation, using any of the methods above:
1. Start a [Rails console](../administration/operations/rails_console.md).
1. Find the user and skip reconfirmation:
```ruby
user = User.find(1)
user.skip_reconfirmation!
```
1. Try to sign in again.
## Reset your root password
The previously described steps can also be used to reset the root password.
In normal installations where the username of root account hasn't been changed
manually, the Rake task can be used with username `root` to reset the root
password.
If the username was changed to something else and has been forgotten, one
possible way is to reset the password using Rails console with user ID `1` (in
almost all the cases, the first user is the default administrator account).
<!-- ## 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. -->
1. Attempt to sign in again.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment