Skip to main content

Integration guide: Morio and Hashicorp Vault

Morio can be integrated with Hashicorp Vault. When doing so, Morio can be instructed to read secrets from Vault, rather than store them locally as encrypted data.

Morio cannot and will not write to Vault. It will only read secrets from it.

OpenBAO Compatibility

After Hashicorp's decision to re-license its software as BSL, Vault was forked as OpenBAO under the wing of the Linux Foundation.

For the time being, we have a single implementation that we refer to as Vault, but as OpenBAO aims for API compatibility, you can also read it as OpenBao.

That being said, we currently only test against Hashicorp Vault.

To make this happen, you need to configure both Morio and Vault, as well as ensure Morio has HTTPS access to Vault.

Ensure connectivity​

For this to work, Morio needs access to your Vault instance on the port Vault listens on HTTPS. That is 9200 by default in Vault, but is also often 443.

Morio configuration​

In the Morio settings, you need a vault key. At the very minimum you need a url. The other values are set to their defaults in this example, so you can leave them out if they match your setup.

vault:
  url: https://vault.morio.it
  jwt_auth_path: morio
  kv_path: secret
  role: morio
  verify_certificate: true

That’s is. You’re done. Now you need to configure Vault.

Vault configuration​

Configuring Vault can be done via the UI or the API. Since the UI does not support everything, we will use examples to do the configuration via the API using curl.

In the examples below, you need to substitute the following:

  • VAULT_TOKEN: Use either the Vault root token, or another token with permissions sufficient for configuring these settings
  • https://vault.morio.it: Use the URL of your own Vault instance

Enable the KV secrets engine​

This may very well already be active, but just in case: the first thing to do is to enable the kv secrets engine:

Enable the KV secrets engine under /secret
curl \
  --header "X-Vault-Token: VAULT_TOKEN" \
  --data '{
    "type":"kv", 
    "options": { "version": "2" }
  }' \
  https://vault.morio.it/v1/sys/mounts/secret
info

Morio only supports version 2 of the kv secrets engine.

Create a JWT authentication method under /morio​

Create a JWT authentication method under /secret
curl \
  --header "X-Vault-Token: VAULT_TOKEN" \
  --data '{"type": "jwt"}' \
  https://vault.morio.it/v1/sys/auth/morio

Grab Morio’s public key from the API​

Make sure to store it, as we will need it in the next command.

Get the public key from the Morio API
curl -k https://example.morio.it/-/api/pubkey.pem

Configure the authentication method we created​

We will configure the Vault authentication method to trust JSON Web Tokens (JWT) signed by Morio’s private key.

Configure the Morio JWT authentication method in Vault
curl \
  --header "X-Vault-Token: VAULT_TOKEN" \
  --data '{
    "type": "jwt", 
    "jwt_supported_algs": "RS256", 
    "jwt_validation_pubkeys": "MORIO_PUBLIC_KEY" 
  }' \
  https://vault.morio.it/v1/sys/auth/morio/config

Create a Vault policy for Morio​

The final step is to create a Vault policy. The example below allows Morio read access to everything under /morio in the kv engine. Adapt it accordingly if you deviated from the defaults.

Create a role under our JWT authentication method in Vault
curl  \
  --header "X-Vault-Token: VAULT_TOKEN" \
  --data '{
    "policy": "# Grant Morio read access to everything under path /morio in the KV engine\npath \"secret/data/morio/*\" {\n  capabilities = [\"read\"]\n}"
  }' \
  https://vault.morio.it/v1/sys/policy/morio

This creates the following morio Vault policy:

# Grant Morio read access to everything under path /morio in the KV engine
path "secret/data/morio/*" {
  capabilities = ["read"]
}

Create a role under the JWT authentication method​

Next we create a role for Morio under our new JWT authentication method and assign our policy to it.

Create a role under our JWT authentication method in Vault
curl  \
  --header "X-Vault-Token: VAULT_TOKEN" \
  --data '{
    "name": "morio",
    "role_type": "jwt",
    "bound_audiences": "morio",
    "user_claim": "trigger",
    "user_claim_json_pointer": true,
    "token_policies": "morio"
  }' \
  https://vault.morio.it/v1/sys/auth/morio/role/morio

Using Vault secrets​

To use a Vault secret, define it in the tokens.secrets settings.

  • The key can be any name you want, although we recommend using the same key name in Morio as in Vault.
  • The value should be an object with a vault key and a value like: path/in/kv:SECRET_NAME

Example:

tokens:
  secrets:
    SECRET_FROM_VAULT:
      vault: morio/production:SECRET_FROM_VAULT

Then, you can reference this secret in the configuration just like any other: {{ SECRET_FROM_VAULT }}.

Summary​

In this guide we have configured Morio to integrate with Hashicorp Vault so that Morio can read secrets from Vault.

To do so, we went through these steps: