mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-11-02 11:38:02 +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
|
||||
```
|
||||
@@ -43,6 +43,30 @@ $ vault auth tune -audit-non-hmac-request-keys=value1 -audit-non-hmac-request-ke
|
||||
Success! Tuned the auth method at: github/
|
||||
```
|
||||
|
||||
User lockout feature is only supported for userpass, ldap, and approle auth methods.
|
||||
|
||||
```shell-session
|
||||
$ vault auth tune -user-lockout-threshold=10 -user-lockout-duration=10m userpass/
|
||||
Success! Tuned the auth method at: userpass/
|
||||
```
|
||||
|
||||
View the current configuration of the auth method enabled at "userpass/".
|
||||
|
||||
```shell-session
|
||||
$ vault read sys/auth/userpass/tune
|
||||
Key Value
|
||||
--- -----
|
||||
default_lease_ttl 768h
|
||||
description n/a
|
||||
force_no_cache false
|
||||
max_lease_ttl 768h
|
||||
token_type default-service
|
||||
user_lockout_counter_reset_duration 0s
|
||||
user_lockout_disable false
|
||||
user_lockout_duration 10m
|
||||
user_lockout_threshold 10
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
The following flags are available in addition to the [standard set of
|
||||
@@ -87,3 +111,15 @@ flags](/docs/commands) included on all commands.
|
||||
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
|
||||
to use. The new version will not start running until the mount is
|
||||
[reloaded](/docs/commands/plugin/reload).
|
||||
|
||||
- `-user-lockout-threshold` `(string: "")` - Specifies the number of failed login attempts
|
||||
after which the user is locked out. User lockout feature was added in Vault 1.13.
|
||||
|
||||
- `-user-lockout-duration` `(duration: "")` - Specifies the duration for which a user will be locked out.
|
||||
User lockout feature was added in Vault 1.13.
|
||||
|
||||
- `-user-lockout-counter-reset-duration` `(duration: "")` - Specifies the duration after which the lockout
|
||||
counter is reset with no failed login attempts. User lockout feature was added in Vault 1.13.
|
||||
|
||||
- `-user-lockout-disable` `(bool: false)` - Disables the user lockout feature if set to true. User lockout feature was added in Vault 1.13.
|
||||
|
||||
|
||||
37
website/content/docs/concepts/user-lockout.mdx
Normal file
37
website/content/docs/concepts/user-lockout.mdx
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: User Lockout
|
||||
description: >-
|
||||
If a user provides bad credentials several times in quick succession,
|
||||
Vault will stop trying to validate their credentials for a while, instead
|
||||
returning immediately with a permission denied error.
|
||||
---
|
||||
|
||||
# User Lockout
|
||||
|
||||
@include 'user-lockout.mdx'
|
||||
|
||||
## Precendence
|
||||
|
||||
The precedence for user lockout configuration is as follows:
|
||||
|
||||
Configuration for an auth mount using tune >> Configuration for an auth method in config file >>
|
||||
Configuration for "all" auth methods in config file >> Default values.
|
||||
|
||||
The precedence for user lockout disable is as follows:
|
||||
|
||||
Disable using environment variable VAULT_DISABLE_USER_LOCKOUT >>
|
||||
Configuration for an auth mount using tune >> Configuration for an auth method in config file >>
|
||||
Configuration for "all" auth methods in config file >> Default values.
|
||||
|
||||
## Configuration
|
||||
|
||||
User lockout parameters can be configured using config file for "all" auth methods or a specific auth method (userpass, ldap, or approle).
|
||||
Please see [user lockout configuration](/docs/configuration/user-lockout#user_lockout-stanza) for more details.
|
||||
|
||||
The user lockout configuration for the auth method at a given path can be tuned using auth tune. Please see [auth tune command](/docs/commands/auth/tune)
|
||||
or [auth tune api](/api-docs/system/auth#tune-auth-method) for more details.
|
||||
|
||||
## API
|
||||
|
||||
Please see [sys/locked-users API](/api-docs/system/user-lockout) for more details.
|
||||
@@ -58,6 +58,10 @@ to specify where the configuration is.
|
||||
- `listener` `([Listener][listener]: <required>)` – Configures how
|
||||
Vault is listening for API requests.
|
||||
|
||||
- `user_lockout` `([UserLockout][user-lockout]: nil)` –
|
||||
Configures the user-lockout behaviour for failed logins. For more information, please see the
|
||||
[user lockout configuration documentation](/docs/configuration/user-lockout).
|
||||
|
||||
- `seal` `([Seal][seal]: nil)` – Configures the seal type to use for
|
||||
auto-unsealing, as well as for
|
||||
[seal wrapping][sealwrap] as an additional layer of data protection.
|
||||
|
||||
67
website/content/docs/configuration/user-lockout.mdx
Normal file
67
website/content/docs/configuration/user-lockout.mdx
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: User Lockout - Configuration
|
||||
description: |-
|
||||
The user_lockout stanza specifies various configurations for user lockout behaviour for
|
||||
failed logins in vault.
|
||||
---
|
||||
# User Lockout
|
||||
|
||||
@include 'user-lockout.mdx'
|
||||
|
||||
## `user_lockout` Stanza
|
||||
|
||||
The `user_lockout` stanza specifies various configurations for user lockout
|
||||
behaviour for failed logins in vault. They can be configured for all supported auth methods
|
||||
(userpass, ldap and approle) using "all" user_lockout stanza name or for a specific auth method
|
||||
using the auth method name in stanza.
|
||||
|
||||
Supported user_lockout stanza names are all, userpass, ldap and approle.
|
||||
|
||||
The configurations for a specific auth method takes precedence over the configurations specified
|
||||
for all auth methods using "all" user_lockout stanza name in the config file.
|
||||
|
||||
## Configuration
|
||||
|
||||
User lockouts configuration is done through the Vault configuration file using
|
||||
the `user_lockout` stanza:
|
||||
|
||||
```hcl
|
||||
user_lockout [NAME] {
|
||||
[PARAMETERS...]
|
||||
}
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```hcl
|
||||
user_lockout "all" {
|
||||
lockout_duration = "10m"
|
||||
lockout_counter_reset = "10m"
|
||||
}
|
||||
|
||||
user_lockout "userpass" {
|
||||
lockout_threshold = "25"
|
||||
lockout_duration = "5m"
|
||||
}
|
||||
|
||||
user_lockout "ldap" {
|
||||
disable_lockout = "true"
|
||||
}
|
||||
```
|
||||
|
||||
Here, user lockout feature will be disabled for ldap auth methods. Userpass auth methods will have lockout threshold of 25,
|
||||
lockout duration of 5 minutes, lockout counter reset of 10 minutes. Approle auth methods will have a lockout threshold of
|
||||
5 (considers default as this value is not configured), lockout duration of 10 minutes and lockout counter reset of 10 minutes.
|
||||
|
||||
The user lockout configuration for the auth method at a given path can be tuned using auth tune. Please see [auth tune command](/docs/commands/auth/tune)
|
||||
or [auth tune api](/api-docs/system/auth#tune-auth-method) for more details.
|
||||
|
||||
## `user_lockout` Parameters
|
||||
|
||||
The following options are available on all telemetry configurations.
|
||||
|
||||
- `lockout_threshold` `(string: "")` - Specifies the number of failed login attempts after which the user is locked out.
|
||||
- `lockout_duration` `(string: "")` - Specifies the duration for which an user will be locked out.
|
||||
- `lockout_counter_reset` `(string: "")` - Specifies the duration after which the lockout counter is reset with no failed login attempts.
|
||||
- `disable_lockout` `(bool: false)` - Disables the user lockout feature if set to true.
|
||||
@@ -94,8 +94,8 @@ These metrics represent operational aspects of the running Vault instance.
|
||||
| `vault.core.in_flight_requests` | Number of in-flight requests. | requests | gauge |
|
||||
| `vault.core.leadership_setup_failed` | Duration of time taken by cluster leadership setup failures which have occurred in a highly available Vault cluster. This should be monitored and alerted on for overall cluster leadership status. | ms | summary |
|
||||
| `vault.core.leadership_lost` | The total duration that a HA cluster node maintained leadership as reported at the last time of loss. If metric is present and has a count greater than zero, that means a leadership change has occurred. Continuing changes or reports of low value could be a cause for monitoring alerts as they would typically imply ongoing flapping of leadership that may rotate between nodes. | ms | summary |
|
||||
|
||||
| `vault.core.license.expiration_time_epoch` | Time as epoch (seconds since Jan 1 1970) at which license will expire. | seconds | gauge |
|
||||
| `vault.core.locked_users` | Number of locked users in Vault. | locked users | gauge |
|
||||
| `vault.core.mount_table.num_entries` | Number of mounts in a particular mount table. This metric is labeled by table type (auth or logical) and whether or not the table is replicated (local or not) | objects | gauge |
|
||||
| `vault.core.mount_table.size` | Size of a particular mount table. This metric is labeled by table type (auth or logical) and whether or not the table is replicated (local or not) | bytes | gauge |
|
||||
| `vault.core.post_unseal` | Duration of time taken by post-unseal operations handled by Vault core | ms | summary |
|
||||
|
||||
23
website/content/partials/user-lockout.mdx
Normal file
23
website/content/partials/user-lockout.mdx
Normal file
@@ -0,0 +1,23 @@
|
||||
If a user provides bad credentials several times in quick succession,
|
||||
Vault will stop trying to validate their credentials for a while, instead returning immediately
|
||||
with a permission denied error. We call this behavior "user lockout". The time for which
|
||||
a user will be locked out is called “lockout duration”. The user will be able to login after the lockout
|
||||
duration has passed. The number of failed login attempts after which the user is locked out is called
|
||||
“lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts,
|
||||
or upon a successful login attempt. The duration after which the counter will be reset to zero
|
||||
after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests
|
||||
i.e, user-based password guessing attacks as well as automated attacks.
|
||||
|
||||
The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts,
|
||||
"lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes.
|
||||
|
||||
The user lockout feature can disabled as follows:
|
||||
- It can be disabled globally using environment variable VAULT_DISABLE_USER_LOCKOUT.
|
||||
- It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using "disable_lockout"
|
||||
parameter within user_lockout stanza in configuration file.
|
||||
Please see [user lockout configuration](/docs/configuration/user-lockout#user_lockout-stanza) for more details.
|
||||
- It can be disabled for a specific auth mount using "auth tune". Please see [auth tune command](/docs/commands/auth/tune)
|
||||
or [auth tune api](/api-docs/system/auth#tune-auth-method) for more details.
|
||||
|
||||
|
||||
~> **NOTE**: This feature is available from Vault version 1.13 and is only supported by userpass, ldap and approle auth methods.
|
||||
@@ -531,6 +531,10 @@
|
||||
"title": "<code>/sys/license/status</code>",
|
||||
"path": "system/license"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/locked-users</code>",
|
||||
"path": "system/user-lockout"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/loggers</code>",
|
||||
"path": "system/loggers"
|
||||
|
||||
@@ -194,6 +194,10 @@
|
||||
{
|
||||
"title": "Duration String Format",
|
||||
"path": "concepts/duration-format"
|
||||
},
|
||||
{
|
||||
"title": "User Lockout",
|
||||
"path": "concepts/user-lockout"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -397,6 +401,10 @@
|
||||
"title": "<code>ui</code>",
|
||||
"path": "configuration/ui"
|
||||
},
|
||||
{
|
||||
"title": "<code>user_lockout</code>",
|
||||
"path": "configuration/user-lockout"
|
||||
},
|
||||
{
|
||||
"title": "<code>Log Completed Requests</code>",
|
||||
"path": "configuration/log-requests-level"
|
||||
|
||||
Reference in New Issue
Block a user