Skip to content

RS: Fixed outdated password rotation and authorize user docs #1564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
May 16, 2025
Merged

RS: Fixed outdated password rotation and authorize user docs #1564

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
5923b05
DOC-5248 RS: Fixed outdated password rotation docs
rrelledge May 14, 2025
0e046cb
Added breaking changes for /users/password and /users/authorize APIs …
rrelledge May 15, 2025
02451fd
DOC-5248 Feedback update to add 401 status codes back to API reference
rrelledge May 15, 2025
677545c
Updated 401 status code links
rrelledge May 15, 2025
87e5840
Fixed /users/authorize breaking change description
rrelledge May 15, 2025
8df3351
Removed redundant wording
rrelledge May 15, 2025
1b08d99
Fixed /users/authorize breaking change description on 7.8 release not…
rrelledge May 15, 2025
e1f4bfe
Updated outdated /users/authorize REST API reference
rrelledge May 15, 2025
7d33aa1
Added ttl default, min, and max values to /users/authorize API reference
rrelledge May 15, 2025
ca0d9bb
Fixed another error in /users/authorize breaking changes description
rrelledge May 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 17 additions & 32 deletions content/operate/rs/references/rest-api/requests/users/password.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@ weight: $weight

| Method | Path | Description |
|----------------------------|----------------------|-----------------------------|
| [PUT](#update-password) | `/v1/users/password` | Change an existing password |
| [POST](#add-password) | `/v1/users/password` | Add a new password |
| [DELETE](#delete-password) | `/v1/users/password` | Delete a password |
| [PUT](#update-password) | `/v1/users/password` | Replace the password of the authenticated user |
| [POST](#add-password) | `/v1/users/password` | Add a new password for the authenticated user |
| [DELETE](#delete-password) | `/v1/users/password` | Delete a password for the authenticated user |

## Update password {#update-password}

PUT /v1/users/password

Reset the password list of an internal user to include a new password.
Replaces the password list of the user making this request with a single new password.

### Request {#put-request}

Expand All @@ -33,8 +33,6 @@ Reset the password list of an internal user to include a new password.

```json
{
"username": "johnsmith",
"old_password": "a password that exists in the current list",
"new_password": "the new (single) password"
}
```
Expand All @@ -47,12 +45,10 @@ Reset the password list of an internal user to include a new password.

#### Request body

The request must contain a single JSON object with the following fields:
The request must contain a JSON object with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| username | string | Affected user (required) |
| old_password | string | A password that exists in the current list (required) |
| new_password | string | The new password (required) |

### Response {#put-response}
Expand All @@ -74,16 +70,14 @@ The following are possible `error_code` values:

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, password changed |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing parameters. |
| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | The user is unauthorized. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to reset password to a non-existing user. |
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, password changed. |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters. |

## Add password {#add-password}

POST /v1/users/password

Add a new password to an internal user's passwords list.
Adds a new password to the password list of the user making this request.

### Request {#post-request}

Expand All @@ -95,8 +89,6 @@ Add a new password to an internal user's passwords list.

```json
{
"username": "johnsmith",
"old_password": "an existing password",
"new_password": "a password to add"
}
```
Expand All @@ -109,13 +101,11 @@ Add a new password to an internal user's passwords list.

#### Request body

The request must contain a single JSON object with the following fields:
The request must contain a JSON object with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| username | string | Affected user (required) |
| old_password | string | A password that exists in the current list (required) |
| new_password | string | The new (single) password (required) |
| new_password | string | New password to add (required) |

### Response {#post-response}

Expand All @@ -136,15 +126,14 @@ The following are possible `error_code` values:

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, new password was added to the list of valid passwords. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing parameters. |
| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | The user is unauthorized. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to add a password to a non-existing user. |
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, new password was added to the list of valid passwords. |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters. |

## Delete password {#delete-password}

DELETE /v1/users/password

Delete a password from an internal user's passwords list.
Deletes a password from the password list of the user making this request.

### Request {#delete-request}

Expand All @@ -156,7 +145,6 @@ Delete a password from an internal user's passwords list.

```json
{
"username": "johnsmith",
"old_password": "an existing password"
}
```
Expand All @@ -169,11 +157,10 @@ Delete a password from an internal user's passwords list.

#### Request body

The request must contain a single JSON with the following fields:
The request must contain a JSON object with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| username | string | Affected user (required) |
| old_password | string | Existing password to be deleted (required) |

### Response {#delete-response}
Expand All @@ -192,7 +179,5 @@ The following are possible `error_code` values:

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, new password was deleted from the list of valid passwords. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing parameters. |
| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | The user is unauthorized. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to delete a password to a non-existing user. |
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, new password was deleted from the list of valid passwords. |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters. |
30 changes: 13 additions & 17 deletions content/operate/rs/security/access-control/manage-passwords/rotate-passwords.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ weight: 70

Redis Enterprise Software lets you implement password rotation policies using the [REST API]({{< relref "/operate/rs/references/rest-api" >}}).

You can add a new password for a database user without immediately invalidating the old one (which might cause authentication errors in production).
You can add a new password for a database user without immediately invalidating the old one to prevent possible authentication errors in production.

{{< note >}}
Password rotation does not work for the default user. [Add additional users]({{< relref "/operate/rs/security/access-control/create-users" >}}) to enable password rotation.
Expand All @@ -27,7 +27,7 @@ you can set a [password expiration policy]({{< relref "/operate/rs/security/acce
However, for database connections that rely on password authentication,
you need to allow for authentication with the existing password while you roll out the new password to your systems.

With the Redis Enterprise Software REST API, you can add additional passwords to a user account for authentication to the database or the Cluster Manager UI and API.
With the Redis Enterprise Software REST API, you can add additional passwords to your user account for authentication to the database or the Cluster Manager UI and API.

After the old password is replaced in the database connections, you can delete the old password to finish the password rotation process.

Expand All @@ -41,13 +41,13 @@ The new password cannot already exist as a password for the user and must meet t

## Rotate password

To rotate the password of a user account:
To rotate your password:

1. Add an additional password to a user account with [`POST /v1/users/password`]({{< relref "/operate/rs/references/rest-api/requests/users/password#add-password" >}}):
1. Add an additional password to your password list with [`POST /v1/users/password`]({{< relref "/operate/rs/references/rest-api/requests/users/password#add-password" >}}). You must provide the relevant username and current password for [basic authentication]({{<relref "/operate/rs/references/rest-api#authentication">}}) credentials when you send the request.

```sh
POST https://[host][:port]/v1/users/password
'{"username":"<username>", "old_password":"<an_existing_password>", "new_password":"<a_new_password>"}'
POST https://<host>:<port>/v1/users/password
{ "new_password": "<a_new_password>" }
```

After you send this request, you can authenticate with both the old and the new password.
Expand All @@ -56,26 +56,22 @@ To rotate the password of a user account:
1. Delete the original password with [`DELETE /v1/users/password`]({{< relref "/operate/rs/references/rest-api/requests/users/password#update-password" >}}):

```sh
DELETE https://[host][:port]/v1/users/password
'{"username":"<username>", "old_password":"<an_existing_password>"}'
DELETE https://<host>:<port>/v1/users/password
{ "old_password": "<an_existing_password>" }
```

If there is only one valid password for a user account, you cannot delete that password.

## Replace all passwords

You can also replace all existing passwords for a user account with a single password that does not match any existing passwords.
You can also replace all existing passwords for your user account with a single password that does not match any existing passwords.
This can be helpful if you suspect that your passwords are compromised and you want to quickly resecure the account.

To replace all existing passwords for a user account with a single new password, use [`PUT /v1/users/password`]({{< relref "/operate/rs/references/rest-api/requests/users/password#delete-password" >}}):
To replace your passwords, use [`PUT /v1/users/password`]({{< relref "/operate/rs/references/rest-api/requests/users/password#delete-password" >}}). You must provide the relevant username and current password for [basic authentication]({{<relref "/operate/rs/references/rest-api#authentication">}}) credentials when you send the request.

```sh
PUT https://[host][:port]/v1/users/password
'{"username":"<username>", "old_password":"<an_existing_password>", "new_password":"<a_new_password>"}'
PUT https://<host>:<port>/v1/users/password
{ "new_password": "<a_new_password>" }
```

All of the existing passwords are deleted and only the new password is valid.

{{<note>}}
If you send the above request without specifying it is a `PUT` request, the new password is added to the list of existing passwords.
{{</note>}}
After this request, all of your existing passwords are deleted and only the new password is valid.