Skip to content

Commit ecd0b4c

Browse files
rrelledgerrelledge
authored
RS: Authentication header is required for /users/password API (#1598)
* Copied fixes for outdated password rotation and authorize user docs to RS 7.8 version * DOC-5270 RS: Authentication header is required for /users/password API
1 parent 878fdb7 commit ecd0b4c

File tree

4 files changed

+54
-69
lines changed

4 files changed

+54
-69
lines changed

‎content/operate/rs/7.8/references/rest-api/requests/users/authorize.md

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@ url: '/operate/rs/7.8/references/rest-api/requests/users/authorize/'
1414

1515
| Method | Path | Description |
1616
|--------|------|-------------|
17-
| [POST](#post-authorize) | `/v1/users/authorize` | Authorize a user |
17+
| [POST](#post-authorize) | `/v1/users/authorize` | Generate a token to authorize an authenticated user |
1818

1919
## Authorize user {#post-authorize}
2020

2121
POST /v1/users/authorize
2222

23-
Generate a JSON Web Token (JWT) for a user to use as authorization to access the REST API.
23+
Generates a JSON Web Token (JWT) for a user to use as authorization to access the REST API. The request authentication header must include the relevant username and password.
2424

2525
### Request {#post-request}
2626

@@ -30,12 +30,13 @@ Generate a JSON Web Token (JWT) for a user to use as authorization to access the
3030

3131
#### Example JSON body
3232

33-
```json
34-
{
35-
"username": "user@redislabs.com",
36-
"password": "my_password"
37-
}
38-
```
33+
The request body is optional unless you want to specify the token's time to live:
34+
35+
```json
36+
{
37+
"ttl": <time_in_seconds>
38+
}
39+
```
3940

4041
#### Request headers
4142
| Key | Value | Description |
@@ -45,19 +46,19 @@ Generate a JSON Web Token (JWT) for a user to use as authorization to access the
4546

4647
#### Request body
4748

48-
Include a [JWT authorize object]({{< relref "/operate/rs/7.8/references/rest-api/objects/jwt_authorize" >}}) with a valid username and password in the request body.
49+
Optionally include a JSON object in the request body to specify the time to live (`ttl`), which determines the amount of time in seconds the token will be valid. The default `ttl` is `300` seconds. The minimum `ttl` is `1` second and the maximum `ttl` is `86400` seconds.
4950

5051
### Response {#post-response}
5152

5253
Returns a JSON object that contains the generated access token.
5354

5455
#### Example JSON body
5556

56-
```json
57-
{
58-
"access_token": "eyJ5bGciOiKIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXViOjE0NjU0NzU0ODYsInVpZFI1IjEiLCJleHAiOjE0NjU0Nz30OTZ9.2xYXumd1rDoE0edFzcLElMOHsshaqQk2HUNgdsUKxMU"
59-
}
60-
```
57+
```json
58+
{
59+
"access_token": "eyJ5bGciOiKIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXViOjE0NjU0..."
60+
}
61+
```
6162

6263
### Error codes {#post-error-codes}
6364

@@ -73,6 +74,6 @@ The following are possible `error_code` values:
7374

7475
| Code | Description |
7576
|------|-------------|
76-
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The user is authorized. |
77-
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | The request could not be understood by the server due to malformed syntax. |
78-
| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | The user is unauthorized. |
77+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The user is authorized. |
78+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | The request could not be understood by the server due to malformed syntax. |
79+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | The user is unauthorized. |

‎content/operate/rs/7.8/references/rest-api/requests/users/password.md

Lines changed: 20 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,15 @@ url: '/operate/rs/7.8/references/rest-api/requests/users/password/'
1414

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

2121
## Update password {#update-password}
2222

2323
PUT /v1/users/password
2424

25-
Reset the password list of an internal user to include a new password.
25+
Replaces the password list of the user making this request with a single new password. The request authentication header must include the relevant username and password.
2626

2727
### Request {#put-request}
2828

@@ -34,8 +34,6 @@ Reset the password list of an internal user to include a new password.
3434

3535
```json
3636
{
37-
"username": "johnsmith",
38-
"old_password": "a password that exists in the current list",
3937
"new_password": "the new (single) password"
4038
}
4139
```
@@ -48,12 +46,10 @@ Reset the password list of an internal user to include a new password.
4846

4947
#### Request body
5048

51-
The request must contain a single JSON object with the following fields:
49+
The request must contain a JSON object with the following fields:
5250

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

5955
### Response {#put-response}
@@ -75,16 +71,15 @@ The following are possible `error_code` values:
7571

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

8378
## Add password {#add-password}
8479

8580
POST /v1/users/password
8681

87-
Add a new password to an internal user's passwords list.
82+
Adds a new password to the password list of the user making this request. The request authentication header must include the relevant username and password.
8883

8984
### Request {#post-request}
9085

@@ -96,8 +91,6 @@ Add a new password to an internal user's passwords list.
9691

9792
```json
9893
{
99-
"username": "johnsmith",
100-
"old_password": "an existing password",
10194
"new_password": "a password to add"
10295
}
10396
```
@@ -110,13 +103,11 @@ Add a new password to an internal user's passwords list.
110103

111104
#### Request body
112105

113-
The request must contain a single JSON object with the following fields:
106+
The request must contain a JSON object with the following fields:
114107

115108
| Field | Type | Description |
116109
|-------|------|-------------|
117-
| username | string | Affected user (required) |
118-
| old_password | string | A password that exists in the current list (required) |
119-
| new_password | string | The new (single) password (required) |
110+
| new_password | string | New password to add (required) |
120111

121112
### Response {#post-response}
122113

@@ -137,15 +128,15 @@ The following are possible `error_code` values:
137128

138129
| Code | Description |
139130
|------|-------------|
140-
| [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. |
141-
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing parameters. |
142-
| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | The user is unauthorized. |
143-
| [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. |
131+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, new password was added to the list of valid passwords. |
132+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters. |
133+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | The user is unauthorized. |
144134

145135
## Delete password {#delete-password}
136+
146137
DELETE /v1/users/password
147138

148-
Delete a password from an internal user's passwords list.
139+
Deletes a password from the password list of the user making this request. The request authentication header must include the relevant username and password.
149140

150141
### Request {#delete-request}
151142

@@ -157,7 +148,6 @@ Delete a password from an internal user's passwords list.
157148

158149
```json
159150
{
160-
"username": "johnsmith",
161151
"old_password": "an existing password"
162152
}
163153
```
@@ -170,11 +160,10 @@ Delete a password from an internal user's passwords list.
170160

171161
#### Request body
172162

173-
The request must contain a single JSON with the following fields:
163+
The request must contain a JSON object with the following fields:
174164

175165
| Field | Type | Description |
176166
|-------|------|-------------|
177-
| username | string | Affected user (required) |
178167
| old_password | string | Existing password to be deleted (required) |
179168

180169
### Response {#delete-response}
@@ -193,7 +182,6 @@ The following are possible `error_code` values:
193182

194183
| Code | Description |
195184
|------|-------------|
196-
| [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. |
197-
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing parameters. |
198-
| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | The user is unauthorized. |
199-
| [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. |
185+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, new password was deleted from the list of valid passwords. |
186+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters. |
187+
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | The user is unauthorized. |

‎content/operate/rs/7.8/security/access-control/manage-passwords/rotate-passwords.md

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ url: '/operate/rs/7.8/security/access-control/manage-passwords/rotate-passwords/
1414

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

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

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

31-
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.
31+
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.
3232

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

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

4343
## Rotate password
4444

45-
To rotate the password of a user account:
45+
To rotate your password:
4646

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

4949
```sh
50-
POST https://[host][:port]/v1/users/password
51-
'{"username":"<username>", "old_password":"<an_existing_password>", "new_password":"<a_new_password>"}'
50+
POST https://<host>:<port>/v1/users/password
51+
{ "new_password": "<a_new_password>" }
5252
```
5353
5454
After you send this request, you can authenticate with both the old and the new password.
@@ -57,26 +57,22 @@ To rotate the password of a user account:
5757
1. Delete the original password with [`DELETE /v1/users/password`]({{< relref "/operate/rs/7.8/references/rest-api/requests/users/password#update-password" >}}):
5858
5959
```sh
60-
DELETE https://[host][:port]/v1/users/password
61-
'{"username":"<username>", "old_password":"<an_existing_password>"}'
60+
DELETE https://<host>:<port>/v1/users/password
61+
{ "old_password": "<an_existing_password>" }
6262
```
6363
6464
If there is only one valid password for a user account, you cannot delete that password.
6565
6666
## Replace all passwords
6767
68-
You can also replace all existing passwords for a user account with a single password that does not match any existing passwords.
68+
You can also replace all existing passwords for your user account with a single password that does not match any existing passwords.
6969
This can be helpful if you suspect that your passwords are compromised and you want to quickly resecure the account.
7070
71-
To replace all existing passwords for a user account with a single new password, use [`PUT /v1/users/password`]({{< relref "/operate/rs/7.8/references/rest-api/requests/users/password#delete-password" >}}):
71+
To replace your passwords, use [`PUT /v1/users/password`]({{< relref "/operate/rs/7.8/references/rest-api/requests/users/password#delete-password" >}}). You must provide the relevant username and current password for [basic authentication]({{<relref "/operate/rs/7.8/references/rest-api#authentication">}}) credentials when you send the request.
7272
7373
```sh
74-
PUT https://[host][:port]/v1/users/password
75-
'{"username":"<username>", "old_password":"<an_existing_password>", "new_password":"<a_new_password>"}'
74+
PUT https://<host>:<port>/v1/users/password
75+
{ "new_password": "<a_new_password>" }
7676
```
7777
78-
All of the existing passwords are deleted and only the new password is valid.
79-
80-
{{<note>}}
81-
If you send the above request without specifying it is a `PUT` request, the new password is added to the list of existing passwords.
82-
{{</note>}}
78+
After this request, all of your existing passwords are deleted and only the new password is valid.

‎content/operate/rs/references/rest-api/requests/users/password.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ weight: $weight
2121

2222
PUT /v1/users/password
2323

24-
Replaces the password list of the user making this request with a single new password.
24+
Replaces the password list of the user making this request with a single new password. The request authentication header must include the relevant username and password.
2525

2626
### Request {#put-request}
2727

@@ -78,7 +78,7 @@ The following are possible `error_code` values:
7878

7979
POST /v1/users/password
8080

81-
Adds a new password to the password list of the user making this request.
81+
Adds a new password to the password list of the user making this request. The request authentication header must include the relevant username and password.
8282

8383
### Request {#post-request}
8484

@@ -135,7 +135,7 @@ The following are possible `error_code` values:
135135

136136
DELETE /v1/users/password
137137

138-
Deletes a password from the password list of the user making this request.
138+
Deletes a password from the password list of the user making this request. The request authentication header must include the relevant username and password.
139139

140140
### Request {#delete-request}
141141

0 commit comments

Comments
 (0)