User Lockout Feature in Vault Versions 1.13.0 + – HashiCorp Help Center

The User Lockout feature, introduced in Vault version 1.13.0 and available in subsequent versions, is designed to enhance security by mitigating unauthorized access through repeated failed login attempts. This article provides an in-depth understanding of the User Lockout feature, its activation criteria, its impact on user authentication, and its configuration options.

Overview

The User Lockout feature serves as a defense mechanism against both automated and targeted attacks, specifically user-based password guessing attacks and automated brute-force attacks. When a user consecutively provides incorrect credentials for the same account, Vault triggers a "user lockout" behavior. This temporarily suspends authentication validation for that specific user, immediately responding with a "permission denied" error. The purpose of this lockout mechanism is to thwart any further unauthorized login attempts for the affected user. User lockout feature is enabled by default when upgrading to a version > 1.13.0+.

Activation Criteria

The User Lockout feature is subject to the following activation criteria:

1. Consecutive Failed Attempts: A user must consecutively enter incorrect credentials a specified number of times before the lockout mechanism is triggered.

2. Same User Account: The failed login attempts must occur for the same user account.

3. Lockout Threshold: By default, the lockout threshold is set to 5 consecutive failed login attempts.

Lockout Duration and User-specific Lockout

Once the lockout threshold is breached, the affected user's account is subjected to a lockout period, during which authentication attempts are immediately met with a "permission denied" error. This lockout period is referred to as the "lockout duration". By default, the lockout duration is set to 15 minutes.

NOTE: It's important to note that the User Lockout feature operates on a per-user basis. If User A surpasses the lockout threshold, only User A's account will be locked out. Other users will not be affected by this lockout event.

Lockout Counter Reset

To prevent indefinite lockout, the lockout threshold counter is reset to zero after a period of no failed login attempts or upon a successful login. The duration after which the counter will be reset to zero when no login attempts occur is known as the "lockout counter reset". This mechanism ensures that legitimate users are not permanently locked out due to temporary issues.

Disabling User Lockout

The User Lockout feature is enabled by default in Vault versions 1.13.0 + . However, there are scenarios where you might need to disable this feature, such as in specific security configurations or environments. Here are the available methods for disabling User Lockout:

1. Global Disabling: To disable the User Lockout feature globally for all users, you can utilize the environment variable VAULT_DISABLE_USER_LOCKOUT.

2. Auth Method Level Disabling: It is possible to disable User Lockout for specific supported authentication methods, including ldap, userpass, and approle. This can be achieved using the disable_lockout parameter within the user_lockout stanza in the configuration file.

3. Mount Level Disabling: If fine-grained control is required, you can disable User Lockout for a particular authentication mount using the auth tune command or the auth tune API.

Configuration and Precedence

User Lockout configuration is managed through the Vault configuration file using the user_lockout stanza. Configuration options and their values dictate the behavior of the lockout feature for different authentication methods.

The precedence of configurations is as follows:

1. Configuration for a specific auth method using the auth method name in the stanza.
2. Configuration for "all" auth methods using the user_lockout stanza with the name "all".
3. Default values.

Example Configuration

For instance, the following configurations showcase different scenarios:

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, the User Lockout feature is disabled for LDAP authentication methods, lockout threshold and duration are adjusted for userpass auth methods, and default values are used for approle auth methods.

Operational Consideration

Currently, there are no messages in the operational logs that explicitly indicate the activation of the User Lockout feature. When a user is locked out due to consecutive failed login attempts, the only feedback provided is a "permission denied" error. This operational behavior underscores the feature's discreet yet effective approach to security.

Tuning a mount to disable user lockout such as using the CLI vault auth tune or the API does not give any indication of that flag has been flipped, either via vault auth list -detailed or vault read sys/auth.

Furthermore, there is no user interface implementation available for managing this feature or for unlocking users who have been locked out.

API and Documentation

For comprehensive information about locked users, related API details, and specific usage instructions, refer to the sys/locked-users API documentation.

In conclusion, the User Lockout feature, present in Vault versions 1.13.0 + , serves as an essential defense against unauthorized access attempts. Its activation based on consecutive failed login attempts, lockout threshold, and user-specific lockout duration contributes significantly to enhancing the security posture of Vault deployments.

Resources: