vault-config/README.md

# 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/role-administrator](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](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.

* Optionally from [policies/role-kv-writer/kv-writer.hcl](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](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.