mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-11-02 03:27:54 +00:00
user-lockout documentation changes (#18478)
* added user-lockout documentation changes * add changelog * remove new lines * changing method name * changing lockedusers to locked-users * Update website/content/docs/concepts/user-lockout.mdx Co-authored-by: Meggie <meggie@hashicorp.com> * Update website/content/api-docs/system/user-lockout.mdx Co-authored-by: Meggie <meggie@hashicorp.com> * Update website/content/api-docs/system/user-lockout.mdx Co-authored-by: Meggie <meggie@hashicorp.com> * Update website/content/partials/user-lockout.mdx Co-authored-by: Meggie <meggie@hashicorp.com> * Update website/content/partials/user-lockout.mdx Co-authored-by: Meggie <meggie@hashicorp.com> * adding suggested changes * adding bullet points to disable * Update website/content/api-docs/system/user-lockout.mdx Co-authored-by: Josh Black <raskchanky@users.noreply.github.com> * Update website/content/partials/user-lockout.mdx Co-authored-by: Josh Black <raskchanky@users.noreply.github.com> * Update website/content/docs/commands/auth/tune.mdx Co-authored-by: Mike Palmiotto <mike.palmiotto@hashicorp.com> * Update website/content/docs/commands/auth/tune.mdx Co-authored-by: Mike Palmiotto <mike.palmiotto@hashicorp.com> * Update website/content/docs/concepts/user-lockout.mdx Co-authored-by: Mike Palmiotto <mike.palmiotto@hashicorp.com> Co-authored-by: Meggie <meggie@hashicorp.com> Co-authored-by: Josh Black <raskchanky@users.noreply.github.com> Co-authored-by: Mike Palmiotto <mike.palmiotto@hashicorp.com>
This commit is contained in:
akshya96
@@ -346,13 +346,33 @@ can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
|
||||
- `plugin_version` `(string: "")` – Specifies the semantic version of the plugin
|
||||
to use, e.g. "v1.0.0". Changes will not take effect until the mount is reloaded.
|
||||
|
||||
- `user_lockout_config` `(map<string|string>: nil)` – Specifies the user lockout configuration
|
||||
for the mount. User lockout feature was added in Vault 1.13. These are the possible values:
|
||||
|
||||
- `lockout_threshold` `(string: "")` - Specifies the number of failed login attempts after
|
||||
which the user is locked out, specified as a string like "15".
|
||||
|
||||
- `lockout_duration` `(string: "")` - Specifies the duration for which an user will be locked out,
|
||||
specified as a string duration like "5s" or "30m".
|
||||
|
||||
- `lockout_counter_reset` `(string: "")` - Specifies the duration after which the lockout counter is
|
||||
reset with no failed login attempts, specified as a string duration like "5s" or "30m".
|
||||
|
||||
- `lockout_disable` `(bool: false)` - Disables the user lockout feature for this mount
|
||||
if set to true.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"default_lease_ttl": 1800,
|
||||
"max_lease_ttl": 86400,
|
||||
"audit_non_hmac_request_keys": ["client_nonce"]
|
||||
"audit_non_hmac_request_keys": ["client_nonce"],
|
||||
"user_lockout_config":{
|
||||
"lockout_threshold":"20",
|
||||
"lockout_duration":"5m",
|
||||
"lockout_counter_reset":"5m"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
222
website/content/api-docs/system/user-lockout.mdx
Normal file
222
website/content/api-docs/system/user-lockout.mdx
Normal file
@@ -0,0 +1,222 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: /sys/locked-users - HTTP API
|
||||
description: The `/sys/locked-users` endpoint is used to manage locked users in Vault.
|
||||
---
|
||||
|
||||
# `/sys/locked-users`
|
||||
|
||||
The `/sys/locked-users` endpoint is used to list and unlock locked users in Vault.
|
||||
|
||||
Please visit [user lockout](/docs/concepts/user-lockout) concepts page for more details about the feature.
|
||||
|
||||
## List Locked Users
|
||||
|
||||
This endpoint lists the locked users information in Vault.
|
||||
|
||||
The response will include all child namespaces of the namespace in which the
|
||||
request was made. If some namespace has subsequently been deleted, its path will
|
||||
be listed as "deleted namespace :ID:." Deleted namespaces are reported only for
|
||||
queries in the root namespace because the information about the namespace path
|
||||
is unknown. The response will be returned in the decreasing order of locked user
|
||||
counts.
|
||||
|
||||
This endpoint was added in Vault 1.13.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :--------------- |
|
||||
| `GET` | `/sys/locked-users` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `mount_accessor` `(string, optional)` - Specifies the identifier of the auth mount entry to which the user
|
||||
belongs in the namespace in which the request was made. If no mount accessor is specified,
|
||||
the response will include locked users in all child namespaces of the namespace in which the request was made.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request GET \
|
||||
http://127.0.0.1:8200/v1/sys/locked-users
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
|
||||
"lease_id":"",
|
||||
"renewable":false,
|
||||
"lease_duration":0,
|
||||
"data":{
|
||||
"by_namespace":[
|
||||
{
|
||||
"namespace_id":"BzIex",
|
||||
"namespace_path":"ns1/",
|
||||
"counts": 3,
|
||||
"mount_accessors":[
|
||||
{
|
||||
"mount_accessor":"auth_userpass_79e2fe02",
|
||||
"counts":3,
|
||||
"alias_identifiers":[
|
||||
{"user3"},
|
||||
{"user4"},
|
||||
{"user5"},
|
||||
]
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
"namespace_id":"root",
|
||||
"namespace_path":"",
|
||||
"counts":2,
|
||||
"mount_accessors":[
|
||||
{
|
||||
"mount_accessor":"auth_userpass_837f35fc",
|
||||
"counts":2,
|
||||
"alias_identifiers":[
|
||||
{"user1"},
|
||||
{"user2"}
|
||||
]
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
"namespace_id":"v1lb9",
|
||||
"namespace_path":"ns1/ns2/",
|
||||
"counts":1,
|
||||
"mount_accessors":[
|
||||
{
|
||||
"mount_accessor":"auth_userpass_af8d1d32",
|
||||
"counts":1,
|
||||
"alias_identifiers":[
|
||||
{"user6"}
|
||||
]
|
||||
},
|
||||
]
|
||||
}
|
||||
],
|
||||
"total":6
|
||||
},
|
||||
"wrap_info":null,
|
||||
"warnings":null,
|
||||
"auth":null
|
||||
}
|
||||
```
|
||||
|
||||
For deleted namespaces, the response will look like:
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
|
||||
"lease_id":"",
|
||||
"renewable":false,
|
||||
"lease_duration":0,
|
||||
"data":{
|
||||
"by_namespace":[
|
||||
{
|
||||
"namespace_id":"BzIex",
|
||||
"namespace_path":"ns1/",
|
||||
"counts": 3,
|
||||
"mount_accessors":[
|
||||
{
|
||||
"mount_accessor":"auth_userpass_79e2fe02",
|
||||
"counts":3,
|
||||
"alias_identifiers":[
|
||||
{"user3"},
|
||||
{"user4"},
|
||||
{"user5"},
|
||||
]
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
"namespace_id":"root",
|
||||
"namespace_path":"",
|
||||
"counts":2,
|
||||
"mount_accessors":[
|
||||
{
|
||||
"mount_accessor":"auth_userpass_837f35fc",
|
||||
"counts":2,
|
||||
"alias_identifiers":[
|
||||
{"user1"},
|
||||
{"user2"}
|
||||
]
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
"namespace_id":"v1lb9",
|
||||
"namespace_path":"deleted namespace v1lb9",
|
||||
"counts":1,
|
||||
"mount_accessors":[
|
||||
{
|
||||
"mount_accessor":"auth_userpass_af8d1d32",
|
||||
"counts":1,
|
||||
"alias_identifiers":[
|
||||
{"user6"}
|
||||
]
|
||||
},
|
||||
]
|
||||
}
|
||||
],
|
||||
"total":6
|
||||
},
|
||||
"wrap_info":null,
|
||||
"warnings":null,
|
||||
"auth":null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Sample request with mount accessor
|
||||
|
||||
#### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"mount_accessor": "auth_userpass_af8d1d32"
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--data @payload.json \
|
||||
--request GET \
|
||||
http://127.0.0.1:8200/v1/sys/locked-users
|
||||
```
|
||||
|
||||
## Unlock User
|
||||
|
||||
This endpoint unlocks a locked user with provided mount_accessor and alias_identifier in namespace in which the request was made if locked.
|
||||
This command is idempotent, meaning it succeeds even if user with the given mount_accessor and alias_identifier is not locked.
|
||||
|
||||
|
||||
This endpoint was added in Vault 1.13.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :--------------- |
|
||||
| `POST` | `/sys/locked-users/:mount_accessor/unlock/:alias-identifier` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `mount_accessor` `(string, required)` - Specifies the identifier of the auth mount entry to which the user
|
||||
belongs
|
||||
- `alias_identifier` `(string, required)` - It is the name of the alias (user). For example, if the alias
|
||||
belongs to userpass backend, the name should be a valid username within userpass auth method. If the alias belongs
|
||||
to an approle auth method, the name should be a valid RoleID. If the alias belongs to an ldap auth method, the name
|
||||
should be a valid username.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
http://127.0.0.1:8200/v1/sys/locked-users/auth_userpass_af8d1d32/unlock/bsmith
|
||||
```
|
||||
Reference in New Issue
Block a user