118 lines
5.4 KiB
Markdown
118 lines
5.4 KiB
Markdown
# vault-config
|
|
|
|
Example config for a single-node experimental HashiCorp Vault instance
|
|
|
|
## Get started
|
|
|
|
Make sure Vault has access to:
|
|
* `/vault/file`: storage location for the `file` backend
|
|
* `/vault/logs`: storage location for audit logs
|
|
* `/vault/config`: storage location for config file
|
|
|
|
Run Vault as:
|
|
```
|
|
vault server -config=/vault/config/vault.hcl
|
|
```
|
|
|
|
Refer to [config/vault.hcl](config/vault.hcl) for content.
|
|
|
|
## Configure
|
|
|
|
Once Vault's initialized and with your `root` token in hand log in via the `token` auth method, make the following changes:
|
|
* Add policies from [policies](policies) subdirectory into Vault
|
|
* Create group `administrators`
|
|
* Assign policies `administrator` and `auditor` to that group
|
|
* Create one entity to represent yourself as an administrator
|
|
* Create one alias assigned to that entity for you to use as a username
|
|
* Enable auth method `userpass`
|
|
* Create one `userpass` username named like your alias, define your own password
|
|
* Add your own entity to group `administrators`
|
|
|
|
Log out. Never again use the `root` token unless there's a good reason.
|
|
|
|
Get the Vault command-line client via [vaultproject.io/downloads](https://www.vaultproject.io/downloads). It'll install the Vault service itself along with the command-line client. Just ignore the service or keep it disabled via `systemctl disable --now vault.service`. You only need the `vault` binary.
|
|
|
|
* Authenticate against Vault:
|
|
```
|
|
export VAULT_ADDR='https://fully.qualified.domain.name/'
|
|
vault login
|
|
|
|
# Which will prompt for:
|
|
Token (will be hidden):
|
|
```
|
|
Enter your personal alias' token, do not ever again use the `root` token.
|
|
|
|
* Enable audit file device (in non-Vault-speak "the audit log file"):
|
|
```
|
|
# Enable
|
|
vault audit enable file file_path=/vault/logs/audit.log
|
|
|
|
# Expected output:
|
|
Success! Enabled the file audit device at: file/
|
|
```
|
|
Confirm:
|
|
```
|
|
# Confirm
|
|
vault audit list
|
|
|
|
# Expected output
|
|
Path Type Description
|
|
---- ---- -----------
|
|
file/ file n/a
|
|
```
|
|
* We're going to allow all human users to change their own `userpass` password. The policy to do so is at [policies/role-human/change-own-password.hcl](policies/role-human/change-own-password.hcl). For a hands-on example of an actual password change via HTTP API see [Hands-on](#hands-on) but first:
|
|
|
|
* Before you can load the policy into Vault you need to replace the string `ACCESSOR` in it with _your_ particular `userpass` accessor. Get it like so:
|
|
```
|
|
# List auth methods
|
|
vault auth list
|
|
|
|
# Expected result similar to:
|
|
Path Type Accessor Description
|
|
---- ---- -------- -----------
|
|
token/ token auth_token_d3aad127 token based credentials
|
|
userpass/ userpass auth_userpass_6671d643 n/a
|
|
```
|
|
Over in [policies/role-human/change-own-password.hcl](policies/role-human/change-own-password.hcl) replace `ACCESSOR` with what you're seeing here in the Accessor column. Feel free to read up on [templated policies](https://www.vaultproject.io/docs/concepts/policies#templated-policies) for more info.
|
|
|
|
* Load the policy
|
|
* Create a group for humans and assign the policy `change-own-password` to it.
|
|
```
|
|
# Create group
|
|
vault write identity/group name="humans" policies="change-own-password"
|
|
|
|
# Expected output:
|
|
Success! Data written to: identity/group/name/humans
|
|
```
|
|
Adding member entities to your group may be best done via Vault's UI. If we're just talking about a few member entities then the CLI does it like so:
|
|
```
|
|
# Create group
|
|
vault write identity/group name="humans" policies="change-own-password" member_entity_ids="<uuid>,<uuid>,<uuid>"
|
|
|
|
# Expected output:
|
|
Success! Data written to: identity/group/name/humans
|
|
```
|
|
Entity IDs are coming from `vault list identity/entity/id` and/or `vault read identity/entity/name/<name>`.
|
|
|
|
* Optionally [policies/role-cfgmgmt/cfgmgmt.hcl](policies/role-cfgmgmt/cfgmgmt.hcl) gets you started with read-only secrets access for example for a config management tool like Ansible.
|
|
|
|
You'll want to create an Ansible entity with an alias, create both a `token` and a `userpass` alias and use the latter one to authenticate against Vault to retrieve a token. You'll likely want a distinct group where your Ansible entity becomes a member and which uses a policy such as the example at [policies/role-cfgmgmt/cfgmgmt.hcl](policies/role-cfgmgmt/cfgmgmt.hcl).
|
|
|
|
From here on out it's just more of what you already did, feel free to make this fit your own approach.
|
|
|
|
## Clean-up
|
|
|
|
If during any of the above steps you've used the Vault command-line client to authenticate against Vault with your `root` token make sure that client's `~/.vault-token` file is deleted. It contains the verbatim `root` token.
|
|
|
|
## Hands-on
|
|
|
|
How to change a password via API call, see [docs at vaultproject.io](https://www.vaultproject.io/api-docs/auth/userpass#update-password-on-user):
|
|
```
|
|
curl \
|
|
--header 'X-Vault-Token: '"${vaultToken}" \
|
|
--request POST \
|
|
--data '{"password": "'"${newPassword}"'"}' \
|
|
'https://f.q.d.n/v1/auth/userpass/users/'"${username}"'/password'
|
|
```
|
|
If successful Vault will not return data. You may want to make response headers visible via `curl --include`. A successful password change results in an HTTP status code 204.
|