diff --git a/website/source/guides/identity/lease.html.md b/website/source/guides/identity/lease.html.md index 70d29d64c2..aa0d8f489c 100644 --- a/website/source/guides/identity/lease.html.md +++ b/website/source/guides/identity/lease.html.md @@ -50,6 +50,11 @@ renewal and revocation - [Token Auth Method (API)](/api/auth/token/index.html) - [Lease, Renew, and Revoke](/docs/concepts/lease.html) +~> **NOTE:** An [interactive +tutorial](https://www.katacoda.com/hashicorp/scenarios/vault-tokens) is +also available if you do not have a Vault environment to perform the steps +described in this guide. + ## Estimated Time to Complete 10 minutes diff --git a/website/source/guides/identity/policies.html.md b/website/source/guides/identity/policies.html.md index 9d6b148932..2d35f0459e 100644 --- a/website/source/guides/identity/policies.html.md +++ b/website/source/guides/identity/policies.html.md @@ -45,6 +45,12 @@ valid input. - [Policy API](/api/system/policy.html) documentation - [Getting Started guide](/intro/getting-started/policies.html) on policies +~> **NOTE:** An [interactive +tutorial](https://www.katacoda.com/hashicorp/scenarios/vault-policies) is +also available if you do not have a Vault environment to perform the steps +described in this guide. + + ## Estimated Time to Complete 10 minutes diff --git a/website/source/guides/secret-mgmt/app-integration.html.md b/website/source/guides/secret-mgmt/app-integration.html.md new file mode 100644 index 0000000000..9733e0bf8a --- /dev/null +++ b/website/source/guides/secret-mgmt/app-integration.html.md @@ -0,0 +1,442 @@ +--- +layout: "guides" +page_title: "Direct Application Integration - Guides" +sidebar_current: "guides-secret-mgmt-app-integration" +description: |- + This guide demonstrates the use of Consul Template and Envconsul tools. To + understand the difference between the two tools, you are going to retrieve the + same information from Vault. +--- + +# Direct Application Integration + +A modern system requires access to a multitude of secrets: database credentials, +API keys for external services, credentials for service-oriented architecture +communication, etc. Vault steps in to provide a centralized secret management +system. The next step is to decide how your applications acquire the secrets +from Vault. + +This guide introduces ***Consult Template*** and ***Envconsul*** to help you +determine if these tools speed up the integration of your applications once +secrets are securely managed by Vault. + +-> **NOTE:** Both [Consult Template](https://github.com/hashicorp/consul-template) +and [Envconsul](https://github.com/hashicorp/consul-template) are open source +tools. + +### Consul Template + +Despite its name, Consul Template does **not** require a Consul cluster to +operate. It retrieves secrets from Vault and manages the acquisition and renewal +lifecycle. + + +### Envconsul + +Envconsul launches a subprocess which dynamically populates environment +variables from secrets read from Vault. Your applications then read those +environment variables. Despite its name, Envconsul does **not** require a +Consul cluster to operate. It enables flexibility and portability for +applications across systems. + + +## Reference Material + +- [Consult Template](https://github.com/hashicorp/consul-template) +- [Envconsul](https://github.com/hashicorp/consul-template) +- [Secret as a Service: Dynamic Secrets](/guides/secret-mgmt/dynamic-secrets.html) + + +## Estimated Time to Complete + +10 minutes + + +## Challenge + +If your application code or script contains some secrets (e.g. database +credentials), it makes a good sense to manage the secrets using Vault. However, +it means that your application will need to retrieve the secrets at runtime. +Does that mean the application developers must make some code change? + +Is there an easy way to retrieve the secrets from Vault and populate the +application code or script with secrets as needed? + + +## Solution + +Both ***Consult Template*** and ***Envconsul*** provide first-class support for +Vault. Leveraging these tools can minimize the level of changes introduced to +your applications. Depending on the current application design, you may not need +to make minimal to no code change. + + +## Prerequisites + +To perform the tasks described in this guide, you need: + +- A [Vault environment](/intro/getting-started/install.html) +- [Consul Template](https://releases.hashicorp.com/consul-template/) +- [Envconsul](https://releases.hashicorp.com/envconsul/) +- [PostgreSQL](#postgresql) + + +### PostgreSQL + +This guide uses the database secrets engine to demonstrate the use of Consul +Template and Envconsul. Therefore, you need a +[PostgreSQL](https://www.postgresql.org/download/) server to connect to. + +~> Complete the [Secret as a Service: Dynamic +Secrets](/guides/secret-mgmt/dynamic-secrets.html) guide first if you are not +familiar with `database` secrets engine. + + + +### Policy requirements + +-> **NOTE:** For the purpose of this guide, you can use **`root`** token to work +with Vault. However, it is recommended that root tokens are only used for just +enough initial setup or in emergencies. As a best practice, use tokens with +appropriate set of policies based on your role in the organization. + +To perform all tasks demonstrated in this guide, your policy must include the +following permissions: + +```shell +# Enable database secrets engines at "database/" path +path "sys/mounts/database" { + capabilities = [ "create", "read", "update", "delete", "list" ] +} + +# Configure the database secret engine and create roles +path "database/*" { + capabilities = [ "create", "read", "update", "delete", "list" ] +} + +# Write ACL policies +path "sys/policy/*" { + capabilities = [ "create", "read", "update", "delete", "list" ] +} + +# Manage tokens for Consul Template & Envconsul to use +path "auth/token/create" { + capabilities = [ "create", "read", "update", "delete", "list", "sudo" ] +} +``` + +If you are not familiar with policies, complete the +[policies](/guides/identity/policies.html) guide. + + + +## Steps + +This guide demonstrates the use of Consul Template and Envconsul tools. To +understand the difference between the two tools, you are going to retrieve the +same information from Vault. + +1. [Setup Database Secrets Engine](#step1) +1. [Generate Client Token](#step2) +1. [Use Consul Template to Populate DB Credentials](#step3) +1. [Use Envconsul to Retrieve DB Credentials](#step4) + + +### Step 1: Setup Database Secrets Engine + +In this step, you are going to enable and configure the `database` secrets +engine using `postgresql-database-plugin` where the database connection URL is +`postgresql://root:rootpassword@localhost:5432/myapp`. + +> **NOTE:** Your database connection URL is most likely different from this +example. Be sure to use the correct [connection URL] +(http://localhost:4567/api/secret/databases/postgresql.html#connection_url) to +match your environment. + +~> Refer to the [PostgreSQL Database Secrets +Engine](/docs/secrets/databases/postgresql.html) documentation or [Secret as a +Service: Dynamic Secrets](/guides/secret-mgmt/dynamic-secrets.html) guide if you +are not familiar with `database` secrets engine. The detailed description of +working with `database` secrets engine is out of scope for this guide. + + +#### CLI command + +```shell +# First, enable the database secrets engine +$ vault secrets enable database + +# Configure the secret engine with appropriate parameter values +$ vault write database/config/postgresql + plugin_name=postgresql-database-plugin \ + allowed_roles=* \ + connection_url=postgresql://root:rootpassword@localhost:5432/myapp + +# Create readonly.sql to define a role permission in SQL +$ tee readonly.sql <Step 2: Generate Client Token + +Consul Template tool itself is a Vault client. Therefore, it must have a valid +token with policies permitting it to retrieve secrets from `database` secret +engine you just configured in [Step 1](#step1). + +First, create a policy definition file, `db_creds.hcl`. This policy allows read +operation on the `database/creds/readonly` path to obtain the dynamically +generated username and password to access the PostgreSQL database. In addition, +the policy allows renewal of the lease if necessary. + +**`db_creds.hcl`**: + +```hcl +path "database/creds/readonly" { + capabilities = [ "read" ] +} + +path "/sys/leases/renew" { + capabilities = [ "update" ] +} +``` + +Now, create a policy named, `db_creds` and generate a token with this policy +attached. + + +### CLI Command + +```shell +# Create a `db_creds` policy +$ vault policy write db_creds db_creds.hcl + +# Create a token with db_creds policy: +$ vault token create -policy="db_creds" +Key Value +--- ----- +token 89956bf1-6f4d-435d-4cf3-7496e9520a87 +token_accessor 319eddff-42a1-eb2b-801e-dd8a0c0b07b4 +token_duration 768h +token_renewable true +token_policies ["db_creds" "default"] +identity_policies [] +policies ["db_creds" "default"] +``` + +**NOTE:** This is the token that Consul Template uses to talk to Vault. +Copy the **`token`** value and proceed to [Step 3](#step3). + + +#### API call using cURL + +```shell +# Create an API request payload +$ tee payload.json <Step 3: Use Consul Template to Populate DB Credentials + +Assume that your application requires PostgreSQL database credentials to read +data. Its configuration file, **`config.yml`** looks like: + +```plaintext +username: "" +password: "" +database: "myapp" +``` + +To have Consul Template to populate the `` and ``, you +need to create a template file with Consul Template [templating +language](https://github.com/hashicorp/consul-template#templating-language). + + +1. Create a template file by replacing the username and password with + Consul Template syntax and save it as **`config.yml.tpl`**. The file should + contain the following: + + ```plaintext + --- + {{- with secret "database/creds/readonly" }} + username: "{{ .Data.username }}" + password: "{{ .Data.password }}" + database: "myapp" + {{- end }} + ``` + + -> **NOTE:** This template reads secrets from `database/creds/readonly` + path in Vault. Set the `username` parameter value to "`.Data.username`" of + the secret output. Similarly, set the `password` to "`.Data.password`" value. + +1. Execute the `consul-template` command to populate `config.yml` file. + + The Consul Template command is: `consul-template -template=":"` + + The input file is the **`config.yml.tpl`** and specify the desired output + file name to be **`config.yml`**: + + ```plaintext + $ VAULT_TOKEN= consul-template -template="config.yml.tpl:config.yml" -once + ``` + + While `` is the token you copied at [Step 2](#step2). + + +1. Open the generated **`config.yml`** file to verify its content. It should + look similar to: + + ```plaintext + $ cat config.yml + --- + username: "v-token-readonly-tu17xrtz345uz643980r-1527630039" + password: "A1a-7s0z9y223x2rp6v9" + database: "myapp" + ``` + + The `username` and `password` were retrieved from Vault and populated in the + `config.yml` file. + + +> **Summary**: You need to create a templated version of your application +scripts to leverage Consul Template. However, it requires minimum effort to do +so in comparison to writing an application which invokes Vault API to accomplish +the same. + + + +### Step 4: Use Envconsul to Retrieve DB Credentials + +Create a file named, **`app.sh`** containing the following: + +```hcl +#!/usr/bin/env bash + +cat < Notice that the environment variable name is derived from the secret _path_ +with key name. + +Run the Envconsul tool using the Vault token you generated at [Step 2](#step2). + +```plaintext +$ VAULT_TOKEN= envconsul -upcase -secret database/creds/readonly ./app.sh + +My connection info is: + +username: "v-token-readonly-ww1tq33s7z5uprpxxy68-1527631219" +password: "A1a-u54wut0v605qwz95" +database: "my-app" +``` + +The output should display the `username` and `password` populated. + +The `-upcase` flag tells Envconsul to convert all environment variable keys to +uppercase. Otherwise, the default uses lowercase (e.g. `database_creds_readonly_username`). + + +> **Summary:** If your application is designed to read secrets from environment +variables, Envconsul requires minimal to no code change to integrate with Vault. + + + +## Next steps + +If the integration option is to directly invoke Vault API within your +application, refer to the [_AppRole Pull +Authentication_](/guides/identity/authentication.html) guide to learn about the +AppRole auth method which is designed for applications. diff --git a/website/source/guides/secret-mgmt/cubbyhole.html.md b/website/source/guides/secret-mgmt/cubbyhole.html.md index fc4cefcdea..a2c6b83264 100644 --- a/website/source/guides/secret-mgmt/cubbyhole.html.md +++ b/website/source/guides/secret-mgmt/cubbyhole.html.md @@ -26,6 +26,11 @@ long as its policy allows it. - [Cubbyhole](/docs/secrets/cubbyhole/index.html) - [Response Wrapping](/docs/concepts/response-wrapping.html) +~> **NOTE:** An [interactive +tutorial](https://www.katacoda.com/hashicorp/scenarios/vault-cubbyhole) is +also available if you do not have a Vault environment to perform the steps +described in this guide. + ## Estimated Time to Complete 10 minutes diff --git a/website/source/guides/secret-mgmt/index.html.md b/website/source/guides/secret-mgmt/index.html.md index f73598be6b..d6e6a48fb7 100644 --- a/website/source/guides/secret-mgmt/index.html.md +++ b/website/source/guides/secret-mgmt/index.html.md @@ -31,8 +31,12 @@ demonstrates the secret versioning capabilities provided by KV Secret Engine v2. - [Database Root Credential Rotation](/guides/secret-mgmt/db-root-rotation.html) guide walks you through the steps to enable the rotation of the database root -credentials for those managed by Vault. +credentials for those managed by Vault. - [Cubbyhole Response Wrapping](/guides/secret-mgmt/cubbyhole.html) guide demonstrates a secure method to distribute secrets by wrapping them where only the expecting client can unwrap. + +- [Direct Application Integration](/guides/secret-mgmt/app-integration.html) +guide demonstrates the usage of _Consul Template_ and _Envconsul_ tool to +retrieve secrets from Vault with no or minimum code change to your applications. diff --git a/website/source/guides/secret-mgmt/versioned-kv.html.md b/website/source/guides/secret-mgmt/versioned-kv.html.md index 03c46f2677..c0c39d3e09 100644 --- a/website/source/guides/secret-mgmt/versioned-kv.html.md +++ b/website/source/guides/secret-mgmt/versioned-kv.html.md @@ -23,6 +23,12 @@ demonstrates the new features introduced by the key-value secret engine v2. - [KV Secrets Engine - Version 2](/docs/secrets/kv/kv-v2.html) - [KV Secrets Engine - Version 2 (API)](/api/secret/kv/kv-v2.html) +~> **NOTE:** An [interactive +tutorial](https://www.katacoda.com/hashicorp/scenarios/vault-static-secrets) is +also available if you do not have a Vault environment to perform the steps +described in this guide. + + ## Estimated Time to Complete 10 minutes diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb index 4762f0a0e5..2f2618337b 100644 --- a/website/source/layouts/guides.erb +++ b/website/source/layouts/guides.erb @@ -86,6 +86,9 @@ > Cubbyhole Response Wrapping + > + Direct Application Integration +