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 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/role-administrator 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. 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. For a hands-on example of an actual password change via HTTP API see 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 replace ACCESSOR with what you're seeing here in the Accessor column. Feel free to read up on 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 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.

From here on out it's just more of what you already did, feel free to make this fit your own approach.
Optionally from policies/role-kv-writer/kv-writer.hcl load a policy that allows affected entities to create kv secrets, create new versions for existing secrets and to traverse the UI directory structure of secrets. Entities with this policy will not be able to read secrets nor see if versions exist at a given location.

Permission to also read/view secrets is commented out in the policy file in case you do need this feature.

Assign the policy to a group as needed.

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:

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.