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](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>`.

## 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.