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

93 lines
2 KiB
Markdown
Raw Normal View History

2015-04-19 22:21:35 +00:00
---
layout: "docs"
page_title: "Auth Backend: Username & Password"
sidebar_current: "docs-auth-userpass"
description: |-
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 \
2015-05-08 15:45:29 +00:00
username=foo \
password=bar
2015-04-19 22:21:35 +00:00
```
#### Via the API
2015-05-08 15:49:58 +00:00
The endpoint for the login is `auth/userpass/login/<username>`.
2015-05-08 15:49:58 +00:00
The password should be sent in the POST body encoded as JSON.
2015-05-08 15:49:58 +00:00
```shell
$ curl $VAULT_ADDR/v1/auth/userpass/login/mitchellh \
-d "password=foo"
```
2015-05-08 15:49:58 +00:00
The response will be in JSON. For example:
```javascript
{
"lease_id":"",
"renewable":false,
"lease_duration":0,
"data":null,
"auth":{
"client_token":"c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
"policies":[
"root"
],
"metadata":{
"username":"mitchellh"
},
"lease_duration":0,
"renewable":false
}
}
```
2015-04-19 22:21:35 +00:00
## 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
```
2015-04-19 22:21:35 +00:00
To use the "userpass" auth backend, an operator must configure it with
2015-04-28 18:32:04 +00:00
users that are allowed to authenticate. An example is shown below.
2015-04-19 22:21:35 +00:00
Use `vault help` for more details.
```
$ vault write auth/userpass/users/mitchellh password=foo policies=root
...
```
The above creates a new user "mitchellh" with the password "foo" that
will be associated with the "root" policy. This is the only configuration
necessary.