# Username/Password

The `userpass` auth method allows users to authenticate with Vault using a username and password combination.

The username/password combinations are configured directly to the auth method using the `users/` path. This method cannot read usernames and passwords from an external source.

The method lowercases all submitted usernames, e.g. `Mary` and `mary` are the same entry.

### Authentication

#### Via the CLI

```shell-session
$ vault login -method=userpass \
    username=mitchellh \
    password=foo
```

#### Via the API

```shell-session
$ curl \
    --request POST \
    --data '{"password": "foo"}' \
    http://127.0.0.1:8200/v1/auth/userpass/login/mitchellh
```

The response will contain the token at `auth.client_token`:

```json
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "auth": {
    "client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
    "policies": ["admins"],
    "metadata": {
      "username": "mitchellh"
    },
    "lease_duration": 0,
    "renewable": false
  }
}
```

### Configuration

Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.

1. Enable the userpass auth method:

   ```shell-session
   $ vault auth enable userpass
   ```

   This enables the userpass auth method at `auth/userpass`. To enable it at a different path, use the `-path` flag:

   ```shell-session
   $ vault auth enable -path=<path> userpass
   ```
2. Configure it with users that are allowed to authenticate:

   ```shell-session
   $ vault write auth/<userpass:path>/users/mitchellh \
       password=foo \
       policies=admins
   ```

   This creates a new user "mitchellh" with the password "foo" that will be associated with the "admins" policy. This is the only configuration necessary.

### User lockout

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 be 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 the `disable_lockout` parameter within `user_lockout` stanza in configuration file. Please see user lockout configuration for more details.
* It can be disabled for a specific auth mount using "auth tune". Please see auth tune command or auth tune api for more details.

\~> **NOTE**: This feature is only supported by the userpass, ldap, and approle auth methods.

### API

The Userpass auth method has a full HTTP API. Please see the Userpass auth method API for more details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/vault/tutorials/cli/authentication/username-password.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.