CRUD features to store arbitrary secrets

Starting the Dev Server. It stores Data in-memory and listens on localhost without TLS. It automatically unseals and shows you the unseal key and root access key.

vault server -dev

Configuring the Client

export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_DEV_ROOT_TOKEN_ID=

Check Status

vault status

Writing and Reading a Secret with the Path secret/hello

vault kv put secret/hello foo=world excited=yes

vault kv get secret/hello

JSON is also possible with -format=json

and getting a Field directly

vault kv get -field=foo secret/hello

Deleting a Secret

vault kv delete secret/hello

Secret Engines

By default, Vault enables a secrets engine called kv at the path secret/

For example the aws secrets engine generates AWS IAM access keys on demand. The database secrets engine generates on-demand , time-limited database credentials.

Enable a Secrets Engine

vault secrets enable -path=kv kv

Because the path defaults to the name of the secret engine this is also possible

vault secrets enable kv

To get more information do a list for secrets

vault secrets list

To see all keys in an do a list

vault list kv

Disable a Secrets Engine

When a Secrets Engine is disabled, all secrets are revoked and the corresponding vault data and configuration is removed.

vault secrets disable kv/

What is a Secrets Engine?

Vault behaves similarly to a virtual filesystem. The read/write/delete/list operations are forwarded to the corresponding secrets engine. This is a good abstraction. Vault can interact with environments like AWS IAM, dynamic SQL user creation, etc. all using the same read/write interface.

Dynamic Secrets

vault secrets enable aws

vault write aws/config/root \
    access_key=AKIAI4SGLQPBX6CSENIQ \
    secret_key=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 \
    region=us-east-1

Create a Role

vault write aws/roles/my-role \
        credential_type=iam_user \
        policy_document=-<<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1426528957000",
      "Effect": "Allow",
      "Action": [
        "ec2:*"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}
EOF

Generating a Secret

Now that the aws secrets engine is configured with a role, we can ask Vault to generate an access key par for that role by reading from aws/creds/:role:

vault read aws/creds/my-role

Revoke a Secret

To revoke a secret use vault revoke with the lease ID:

vault lease revoke aws/creds/my-role/0bce0782-32aa-25ec-f61d-c026ff22106

Built-in Help

Vault has a built-in help system that can be used via command-line or API.

It can be used for the root path:

vault path-help aws

Or a specific path:

vault path-help aws/creds/my-non-existent-role

Authentication

When starting vault in dev mode it automatically logs you in as the root user with admin permission. In a real setup one has to authenticate first.

Tokens

Vault supports different authentication mechanisms, but they all funnel into a single session token which we call the Vault token.

Authentication is simply the process by which a user or machine gets a Vault token.

You can create more tokens:

vault token create

By default, this will create a child token of your current token that inherits all the same policies. When a parent token is revoked, children can also be revoked all in one operation

Revoking a token:

vault token revoke 463763ae-0c3b-ff77-e137-af668941465c

To authenticate with a token:

vault login s.6zUkHYmLNbrber5bsgUTJaAC

Auth Methods

In practice one should not use token create but configure an Auth Method like GitHub or LDAP.

vault auth enable github

vault path-help auth/github

A minimal set of configuration is to map teams to policies:

vault write auth/github/config organization=hashicorp
vault write auth/github/map/teams/my-team value=default,my-policy

You can find out which methods are enabled:

$ vault auth list

Path       Type      Description
----       ----      -----------
github/    github    n/a
token/     token     token based credentials

vault auth help github

Login with GItHub

vault login -method=github

The auth method can be disabled:

vault auth disable github

This will revoke any logins from that auth method.

Policies

They control what a user can access. This is called authorization.

There are some built-in policies like root and default.

Policies are authored in HCL and are compatible to JSON.

Writing Policies

A policy can be written from a file:

vault policy write my-policy my-policy.hcl

Or via here document:

vault policy write my-policy -<<EOF
# Normal servers have version 1 of KV mounted by default, so will need these
# paths:
path "secret/*" {
  capabilities = ["create"]
}
path "secret/foo" {
  capabilities = ["read"]
}

# Dev servers have version 2 of KV mounted by default, so will need these
# paths:
path "secret/data/*" {
  capabilities = ["create"]
}
path "secret/data/foo" {
  capabilities = ["read"]
}
EOF

To see the list of policies run vault policy list

To read a policy do:

vault policy read my-policy

Assign a token to the policy:

vault token create -policy=my-policy

Mapping Policies to Auth Methods

Vault is the only authority for policies. But different auth methods are possible. Auth methods must map identities to policies.

For GitHub it is done per team:

vault write auth/github/map/teams/default value=my-policy

Deploy Vault

Configuring Vault

Vault is configured using HCL files:

storage "consul" {
  address = "127.0.0.1:8500"
  path    = "vault/"
}

listener "tcp" {
 address     = "127.0.0.1:8200"
 tls_disable = 1
}

Start Consul:

consul agent -dev

Start Vault:

sudo /opt/vault/vault server -config=/opt/vault/config.hcl

Initializing the Vault

Initialization happens only once when the server is started against a new Backend:

vault operator init

Seal/unseal

Every initialized server starts in the sealed state. The process of teaching Vault how to decrypt the data from the storage is called unsealing the vault.

Unsealing has to happen every time vault starts. It can be done via API or command-line. In order to do so you need the threshold number of unseal keys, e.g. 3 of 5.

Vault uses an algorith called Shamir’s Secret Sharing.

Let’s unseal the Vault:

vault operator unseal

And login with the root token:

vault login s.PDYIcHu1gAwHNjMTCiqmNk45

A single operator can seal the vault:

vault operator seal

Using the HTTP APIs with Authentication

The REST API can be consumed by an Application using the AppRole auth Method.

The App uses a hard to guess role-id and secret-id in order to authenticate.

The Guide can be found here: https://learn.hashicorp.com/vault/getting-started/apis

It is missing there to create the dev-policy:

path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

Web UI

When the Dev Server is started, the UI can be found here:

http://127.0.0.1:8200/ui

For a Non-Dev Server the UI must be activated in the config:

ui = true

listener "tcp" {
  # ...
}

storage "consul" {
  # ...
}