open-vault/website/source/docs/auth/userpass.html.md

layout	page_title	sidebar_current	description
docs	Auth Backend: Username & Password	docs-auth-userpass	The "userpass" auth backend allows users to authenticate with Vault using a username and password.

Auth Backend: Username & Password

Name: userpass

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

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

Authentication

Via the CLI

$ vault auth -method=userpass \
    username=foo \
    password=bar

Via the API

The endpoint for the login is auth/userpass/login/<username>.

The password should be sent in the POST body encoded as JSON.

$ curl $VAULT_ADDR/v1/auth/userpass/login/mitchellh \
    -d '{ "password": "foo" }'

The response will be in JSON. For example:

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

First, you must enable the username/password auth backend:

$ vault auth-enable userpass
Successfully enabled 'userpass' at 'userpass'!

Now when you run vault auth -methods, the username/password backend is available:

Path       Type      Description
token/     token     token based credentials
userpass/  userpass

To use the "userpass" auth backend, an operator must configure it with users that are allowed to authenticate. An example is shown below. Use vault path-help for more details.

$ vault write auth/userpass/users/mitchellh \
    password=foo \
    policies=admins
...

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

API

/auth/userpass/users/[username]

POST

Description

Create a new user or update an existing user. This path honors the distinction between the `create` and `update` capabilities inside ACL policies.

Method

POST

URL

`/auth/userpass/users/`

Parameters

• username required Username for this user.

• password required Password for this user.

• policies optional Comma-separated list of policies. If set to empty string, only the `default` policy will be applicable to the user.

• ttl optional The lease duration which decides login expiration.

• max_ttl optional Maximum duration after which login should expire.

Returns

`204` response code.

GET

Description

Reads the properties of an existing username.

Method

GET

URL

`/auth/userpass/users/[username]`

Parameters

None.

Returns

{
        "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
        "lease_id": "",
        "lease_duration": 0,
        "renewable": false,
        "data": {
                "max_ttl": 0,
                "policies": "default,dev",
                "ttl": 0
        },
        "warnings": null
}

DELETE

Description

Deletes an existing username from the backend.

Method

DELETE

URL

`/auth/userpass/users/[username]`

Parameters

None.

Returns

`204` response code.

/auth/userpass/users/[username]/password

POST

Description

Update the password for an existing user.

Method

POST

URL

`/auth/userpass/users//password`

Parameters

• username required Username for this user.

• password required Password for this user.

Returns

`204` response code.

/auth/userpass/users/[username]/policies

POST

Description

Update the policies associated with an existing user.

Method

POST

URL

`/auth/userpass/users//policies`

Parameters

• username required Username for this user.

• policies optional Comma-separated list of policies. If this is field is not supplied, the policies will be unchanged. If set to empty string, only the `default` policy will be applicable to the user.

Returns

`204` response code.

/auth/userpass/login/[username]

POST

Description

Login with the username and password.

Method

POST

URL

`/auth/userpass/login/`

Parameters

• password required Password for this user.

Returns

{
 "lease_id": "",
 "renewable": false,
 "lease_duration": 0,
 "data": null,
 "warnings": null,
 "auth": {
 	"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
 	"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
 	"policies": ["default"],
 	"metadata": {
 		"username": "vishal"
 	},
 	"lease_duration": 7200,
 	"renewable": true
 }
}

/auth/userpass/users

LIST

Description

List the users registered with the backend.

Method

LIST/GET

URL

`/auth/userpass/users` (LIST) `/auth/userpass/users?list=true` (GET)

Parameters

None

Returns

[
     "devuser",
 "produser"
]