userpass.mdx

layout	page_title	description
docs	Userpass - Auth Methods	The "userpass" auth method allows users to authenticate with Vault using a username and password.

Userpass auth method

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.

This documentation assumes the Username & Password method is mounted at the default /auth/userpass path in Vault. Since it is possible to enable auth methods at any location, please update your CLI calls accordingly with the -path flag.

Authentication

Via the CLI

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

Via the API

$ 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:

{
  "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:

   $ vault auth enable userpass
   

Enable the userpass auth method at the default auth/userpass path. You can choose to enable the auth method at a different path with the -path flag:

$ vault auth enable -path=<path> userpass

1. Configure it with users that are allowed to authenticate:

   $ 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

@include 'user-lockout.mdx'

API

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