From dc95733f5787ec26b41d2a0190f68e4d56a10fb6 Mon Sep 17 00:00:00 2001 From: akshya96 <87045294+akshya96@users.noreply.github.com> Date: Tue, 17 Jan 2023 15:12:16 -0800 Subject: [PATCH] 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 * Update website/content/api-docs/system/user-lockout.mdx Co-authored-by: Meggie * Update website/content/api-docs/system/user-lockout.mdx Co-authored-by: Meggie * Update website/content/partials/user-lockout.mdx Co-authored-by: Meggie * Update website/content/partials/user-lockout.mdx Co-authored-by: Meggie * adding suggested changes * adding bullet points to disable * Update website/content/api-docs/system/user-lockout.mdx Co-authored-by: Josh Black * Update website/content/partials/user-lockout.mdx Co-authored-by: Josh Black * Update website/content/docs/commands/auth/tune.mdx Co-authored-by: Mike Palmiotto * Update website/content/docs/commands/auth/tune.mdx Co-authored-by: Mike Palmiotto * Update website/content/docs/concepts/user-lockout.mdx Co-authored-by: Mike Palmiotto Co-authored-by: Meggie Co-authored-by: Josh Black Co-authored-by: Mike Palmiotto --- website/content/api-docs/system/auth.mdx | 22 +- .../content/api-docs/system/user-lockout.mdx | 222 ++++++++++++++++++ website/content/docs/commands/auth/tune.mdx | 36 +++ .../content/docs/concepts/user-lockout.mdx | 37 +++ website/content/docs/configuration/index.mdx | 4 + .../docs/configuration/user-lockout.mdx | 67 ++++++ website/content/docs/internals/telemetry.mdx | 2 +- website/content/partials/user-lockout.mdx | 23 ++ website/data/api-docs-nav-data.json | 4 + website/data/docs-nav-data.json | 8 + 10 files changed, 423 insertions(+), 2 deletions(-) create mode 100644 website/content/api-docs/system/user-lockout.mdx create mode 100644 website/content/docs/concepts/user-lockout.mdx create mode 100644 website/content/docs/configuration/user-lockout.mdx create mode 100644 website/content/partials/user-lockout.mdx diff --git a/website/content/api-docs/system/auth.mdx b/website/content/api-docs/system/auth.mdx index ee2e6ebbe6..a4381088d8 100644 --- a/website/content/api-docs/system/auth.mdx +++ b/website/content/api-docs/system/auth.mdx @@ -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: 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" + } } ``` diff --git a/website/content/api-docs/system/user-lockout.mdx b/website/content/api-docs/system/user-lockout.mdx new file mode 100644 index 0000000000..497a1cc129 --- /dev/null +++ b/website/content/api-docs/system/user-lockout.mdx @@ -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 +``` \ No newline at end of file diff --git a/website/content/docs/commands/auth/tune.mdx b/website/content/docs/commands/auth/tune.mdx index abc401b86c..529e3949ec 100644 --- a/website/content/docs/commands/auth/tune.mdx +++ b/website/content/docs/commands/auth/tune.mdx @@ -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. + diff --git a/website/content/docs/concepts/user-lockout.mdx b/website/content/docs/concepts/user-lockout.mdx new file mode 100644 index 0000000000..6f769cb5cd --- /dev/null +++ b/website/content/docs/concepts/user-lockout.mdx @@ -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. \ No newline at end of file diff --git a/website/content/docs/configuration/index.mdx b/website/content/docs/configuration/index.mdx index 291b353f3e..639bc9a5ec 100644 --- a/website/content/docs/configuration/index.mdx +++ b/website/content/docs/configuration/index.mdx @@ -58,6 +58,10 @@ to specify where the configuration is. - `listener` `([Listener][listener]: )` – 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. diff --git a/website/content/docs/configuration/user-lockout.mdx b/website/content/docs/configuration/user-lockout.mdx new file mode 100644 index 0000000000..3e4381eecc --- /dev/null +++ b/website/content/docs/configuration/user-lockout.mdx @@ -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. \ No newline at end of file diff --git a/website/content/docs/internals/telemetry.mdx b/website/content/docs/internals/telemetry.mdx index f6c2edb816..304ba1c8c8 100644 --- a/website/content/docs/internals/telemetry.mdx +++ b/website/content/docs/internals/telemetry.mdx @@ -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 | diff --git a/website/content/partials/user-lockout.mdx b/website/content/partials/user-lockout.mdx new file mode 100644 index 0000000000..6b899a2005 --- /dev/null +++ b/website/content/partials/user-lockout.mdx @@ -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. \ No newline at end of file diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index d302f4ab9b..e15b00620a 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -531,6 +531,10 @@ "title": "/sys/license/status", "path": "system/license" }, + { + "title": "/sys/locked-users", + "path": "system/user-lockout" + }, { "title": "/sys/loggers", "path": "system/loggers" diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 636daf2ecb..ebc46f1624 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -194,6 +194,10 @@ { "title": "Duration String Format", "path": "concepts/duration-format" + }, + { + "title": "User Lockout", + "path": "concepts/user-lockout" } ] }, @@ -397,6 +401,10 @@ "title": "ui", "path": "configuration/ui" }, + { + "title": "user_lockout", + "path": "configuration/user-lockout" + }, { "title": "Log Completed Requests", "path": "configuration/log-requests-level"