Re-categorized the guides on the navigation

This commit is contained in:
Yoko Hyakuna 2018-01-26 15:13:15 -08:00
parent d5262f7896
commit 1a532cb993
16 changed files with 273 additions and 70 deletions

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "AppRole Pull Authentication - Guides"
sidebar_current: "guides-authentication"
sidebar_current: "guides-configuration-authentication"
description: |-
Authentication is a process in Vault by which user or machine-supplied
information is verified to create a token with pre-configured policy.

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Generate Root Tokens using Unseal Keys - Guides"
sidebar_current: "guides-generate-root"
sidebar_current: "guides-configuration-generate-root"
description: |-
Generate a new root token using a threshold of unseal keys.
---

View file

@ -0,0 +1,37 @@
---
layout: "guides"
page_title: "Vault Configuration - Guides"
sidebar_current: "guides-configuration"
description: |-
Once a Vault instance has been installed, the next step is to configure auth
backend, secret backend, and manage keys. Vault configuration guides addresses
key concepts in configuring your Vault servers.
---
# Vault Configuration
This guide walks you through Vault configuration topics. Some guides address
fundamental tasks to get the server setup, and some guides introduce more
advanced discussions.
- [Policies](/guides/configuration/policies.html) are used to instrument
Role-Based Access Control (RBAC) by specifying access privileges. Authoring of
policies is probably the first step the Vault administrator performs. This guide
walks you through creating example policies for `admin` and `provisioner` users.
- [AppRole Pull Authentication](/guides/configuration/authentication.html) guide
is an introductory guide introduces the steps to generate tokens for machines
or apps by enabling AppRole auth backend.
- [Token and Leases](/guides/configuration/lease.html) guide helps you
understand how tokens and leases work in Vault. The understanding of the
lease hierarchy and expiration mechanism helps you plan for break glass
procedures and more.
- [Root Token Generation](/guides/configuration/generate-root.html) guide
demonstrates the workflow of regenerating root tokens. It is considered to be a
best practice not to persist the initial **root** token. If a root token needs
to be regenerated, this guide helps you walk through the task.
- [Rekeying & Rotating](/guides/configuration/rekeying-and-rotating.html) guide
provides a high-level overview of Shamir's Secret Sharing Algorithm, and how to
perform _rekey_ and _rotate_ operations in Vault.
- [Building Plugin Backends](/guides/configuration/plugin-backends.html) guide
provides steps to build, register, and mount non-database external plugin
backends.

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Tokens and Leases - Guides"
sidebar_current: "guides-lease"
sidebar_current: "guides-configuration-lease"
description: |-
Tokens are the core method for authentication within Vault. For every
authentication token and dynamic secret, Vault creates a lease

View file

@ -1,21 +1,21 @@
---
layout: "guides"
page_title: "Plugin Backends - Guides"
sidebar_current: "guides-plugin-backends"
sidebar_current: "guides-configuration-plugin-backends"
description: |-
Learn how to build, register, and mount a custom plugin backend.
---
# Introduction
Plugin backends utilize the [plugin system][plugin-system] to enable
third-party secret and auth backends to be mounted.
Plugin backends utilize the [plugin system][plugin-system] to enable
third-party secret and auth backends to be mounted.
It is worth noting that even though [database backends][database-backend]
operate under the same underlying plugin mechanism, they are slightly different
in design than plugin backends demonstrated in this guide. The database backend
in design than plugin backends demonstrated in this guide. The database backend
manages multiple plugins under the same backend mount point, whereas plugin
backends are generic backends that function as either secret or auth backends.
backends are generic backends that function as either secret or auth backends.
This guide provides steps to build, register, and mount non-database external
plugin backends.
@ -35,7 +35,7 @@ plugin_directory="/etc/vault/vault_plugins"
## Build the Plugin Backend
Build the custom backend binary, and move it to the `plugin_directory` path.
In this guide, we will use `mock-plugin` that comes from Vault's
In this guide, we will use `mock-plugin` that comes from Vault's
`logical/plugin/mock` package.
```

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Policies - Guides"
sidebar_current: "guides-governance"
sidebar_current: "guides-configuration-policies"
description: |-
Policies in Vault control what a user can access.
---
@ -285,6 +285,12 @@ path "sys/auth/*"
capabilities = ["create", "read", "update", "delete", "sudo"]
}
# List existing policies
path "sys/policy"
{
capabilities = ["read"]
}
# Create and manage ACL policies
path "sys/policy/*"
{

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Rekeying & Rotating Vault - Guides"
sidebar_current: "guides-rekeying-and-rotating"
sidebar_current: "guides-configuration-rekeying-and-rotating"
description: |-
Vault supports generating new unseal keys as well as rotating the underlying
encryption keys. This guide covers rekeying and rotating Vault's encryption

View file

@ -0,0 +1,14 @@
---
layout: "guides"
page_title: "Guides"
sidebar_current: "getting-started"
description: |-
This section takes you to the Getting Started section.
---
# Vault Getting Started
Welcome to the Vault guides section! If you are just getting started with Vault,
please start with the [Vault introduction](/intro/getting-started/install.html)
instead and then continue on to the guides. The guides provide examples of
common Vault workflows and actions for both beginner and advanced Vault users.

View file

@ -0,0 +1,23 @@
---
layout: "guides"
page_title: "Vault Architecture - Guides"
sidebar_current: "guides-operations"
description: |-
Vault architecture guide covers Vault infrastructure discussions including
installation.
---
# Vault Architecture
Vault Architectures guides address Vault infrastructure discussions. These
guides are designed to help the operations team to plan and install a Vault
cluster that meets your organization's needs.
- [Production Hardening](/guides/architecture/production.html) guide provides
guidance on best practices for a production hardened deployment of Vault.
The recommendations are based on the [security model](/docs/internals/security.html)
and focus on defense in depth.
- [Replication Setup & Guidance](/guides/architecture/replication.html)
walks you through the commands to activate the Vault servers in replication mode.
Please note that [Vault Replication](/docs/vault-enterprise/replication/index.html)
is a Vault Enterprise feature.

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Production Hardening - Guides"
sidebar_current: "guides-production-hardening"
sidebar_current: "guides-operations-production-hardening"
description: |-
This guide provides guidance on best practices for a production hardened deployment of HashiCorp Vault.
---

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Setting up Vault Enterprise Performance Replication - Guides"
sidebar_current: "guides-replication"
sidebar_current: "guides-operations-replication"
description: |-
Learn how to set up and manage Vault Enterprise Performance Replication.
---
@ -177,6 +177,3 @@ mechanisms if DR is necessary in your implementation.
If you need true DR, look at the
[general information page](/docs/vault-enterprise/replication/index.html) for information on Vault's disaster recovery replication.

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Cubbyhole Response Wrapping - Guides"
sidebar_current: "guides-cubbyhole"
sidebar_current: "guides-secret-mgmt-cubbyhole"
description: |-
Vault provides a capability to wrap Vault response and store it in a
"cubbyhole" where the holder of the one-time use wrapping token can unwrap to
@ -35,7 +35,7 @@ long as its policy allows it.
The end-to-end scenario described in this guide involves two personas:
- **`admin`** with privileged permissions to create tokens
- **`apps`** is the receiving client of a wrapped response
- **`apps`** trusted entity retrieving secrets from Vault
## Challenge
@ -43,7 +43,12 @@ In order to tightly manage the secrets, you set the scope of who can do what
using the [Vault policy](/docs/concepts/policies.html) and attach that to
tokens, roles, entities, etc.
How to securely distribute a secret (e.g. token, credentials) to a machine or app?
Think of a case where you have a trusted entity (Chef, Jenkins, etc.) which
reads secrets from Vault. This trusted entity must obtain a token. If the
trusted entity or its host machine was rebooted, it must re-authenticate with
Vault using a valid token.
How can you securely distribute the initial token to the trusted entity?
## Solution
@ -81,6 +86,11 @@ path "auth/token/*" {
path "sys/policy/*" {
capabilities = [ "create", "read", "update", "delete", "list" ]
}
# Manage secret/dev secret backend - for Verification test
path "secret/dev" {
capabilities = [ "create", "read", "update", "delete", "list" ]
}
```
## Steps
@ -106,12 +116,19 @@ Secret](/guide/static-secrets.html) guide.
### <a name="step1"></a>Step 1: Create and wrap a token
(**Persona:** admin)
To solve the [challenge](#challenge) addressed in this guide:
1. More privileged token (`admin`) wraps a secret only the expecting client can
read
2. The receiving client (`app`) unwraps the secret to obtain the token
When the response to `vault token-create` request is wrapped, Vault inserts the
generated token into the cubbyhole of a single-use token, returning that
single-use wrapping token. Retrieving the secret requires an unwrap operation
against this wrapping token.
In this scenario, an [admin user](#personas) creates a token using response wrapping. To perform the steps in this guide, first create a policy for the app.
In this scenario, an [admin user](#personas) creates a token using response
wrapping. To perform the steps in this guide, first create a policy for the app.
`apps-policy.hcl`:
@ -142,16 +159,16 @@ duration of seconds (15s), minutes (20m), or hours (25h).
**Example:**
Generate a token for `apps` persona using response wrapping with TTL of 60
Generate a token for `apps` persona using response wrapping with TTL of 120
seconds.
```shell
$ vault token-create -policy=apps -wrap-ttl=60s
$ vault token-create -policy=apps -wrap-ttl=120
Key Value
--- -----
wrapping_token: 9ac59985-094f-a2de-aed8-bf688e436fbc
wrapping_token_ttl: 1m0s
wrapping_token_ttl: 2m0s
wrapping_token_creation_time: 2018-01-10 00:47:54.970185208 +0000 UTC
wrapping_token_creation_path: auth/token/create
wrapped_accessor: 195763a9-3f26-1fcf-6a1a-ee0a11e76cb1
@ -210,7 +227,7 @@ seconds (15s), minutes (20m), or hours (25h).
To wrap the response of token-create request:
```shell
$ curl --header "X-Vault-Wrap-TTL: 60s" \
$ curl --header "X-Vault-Wrap-TTL: 120" \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"policies":["apps"]}' \
@ -223,7 +240,7 @@ $ curl --header "X-Vault-Wrap-TTL: 60s" \
"data": null,
"wrap_info": {
"token": "e095129f-123a-4fef-c007-1f6a487cfa78",
"ttl": 60,
"ttl": 120,
"creation_time": "2018-01-10T01:43:38.025351336Z",
"creation_path": "auth/token/create",
"wrapped_accessor": "44e8253c-65b4-1690-1bf1-7902a7a6b2aa"
@ -249,9 +266,47 @@ token and none arrives, this may be due to an attacker intercepting the token
and then preventing it from traveling further. This should cause an alert to
trigger an immediate investigation.
The following tasks will be performed to demonstrate the client operations:
1. Create a token with **`default`** policy
2. Authenticate with Vault using this `default` token (less privileged token)
3. Unwrap the secret to obtain more privileged token (**`apps`** persona token)
4. Verify that you can read `secret/dev` using the `apps`token
#### CLI command
To unwrap the secret:
First, create a token with `default` policy:
```shell
# Create a token with `default` policy
$ vault token-create -policy=default
Key Value
--- -----
token 4522b2e8-27fe-bdc5-b932-d982f3166c6c
token_accessor 96108f48-7475-6190-b058-769a2e5ebc8e
token_duration 768h0m0s
token_renewable true
token_policies [default]
# Authenticate using the generated token
$ vault auth 4522b2e8-27fe-bdc5-b932-d982f3166c6c
Successfully authenticated! You are now logged in.
token: 4522b2e8-27fe-bdc5-b932-d982f3166c6c
token_duration: 2764729
token_policies: [default]
# Verify that you do NOT have a permission to read secret/dev
$ vault read secret/dev
Error reading secret/dev: Error making API request.
URL: GET http://<VAULT_ADDRESS>/v1/secret/dev
Code: 403. Errors:
* permission denied
```
The command to unwrap the wrapped secret is:
```shell
$ vault unwrap <WRAPPING_TOKEN>
@ -262,9 +317,6 @@ Or
$ VAULT_TOKEN=<WRAPPING_TOKEN> vault unwrap
```
In this scenario, the wrapped secret is a Vault token. Therefore, it probably
makes better sense to use the second option.
**Example:**
```shell
@ -279,6 +331,8 @@ token_renewable true
token_policies [apps default]
```
Verify that this token has `apps` policy attached.
Once the client acquired the token, future requests can be made using this
token.
@ -291,7 +345,37 @@ No value found at secret/dev
#### API call using cURL
To unwrap the secret, use `/sys/wrapping/unwrap` endpoint:
First, create a token with `default` policy:
```shell
# Create a new token default policy
$ curl --header "X-Vault-Token: ..." --request POST \
--data '{"policies": "default"}' \
https://vault.rocks/v1/auth/token/create | jq
{
...
"auth": {
"client_token": "5fe14760-b0fd-22dc-403c-14a05003b67f",
"accessor": "e709610e-916e-f7e3-b93b-41f4dfdca7a0",
"policies": [
"default"
],
...
}
}
# Verify that you can NOT read secret/dev using default token
$ curl --header "X-Vault-Token: 5fe14760-b0fd-22dc-403c-14a05003b67f" \
--request GET \
https://vault.rocks/v1/secret/dev | jq
{
"errors": [
"permission denied"
]
}
```
Now, unwrap the secret using `/sys/wrapping/unwrap` endpoint:
```shell
$ curl --header "X-Vault-Token: <WRAPPING_TOKEN>" \
@ -339,6 +423,8 @@ $ curl --header "X-Vault-Token: af5f7682-aa55-fa37-5039-ee116df56600" \
}
```
Since there is no data in `secret/dev`, it returns an empty array.
## Additional Discussion
The `cubbyhole` secret backend provides your own private secret storage space

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Secret as a Service - Guides"
sidebar_current: "guides--dataynamic-secrets"
sidebar_current: "guides-secret-mgmt-dataynamic-secrets"
description: |-
Vault can dynamically generate secrets on--dataemand for some systems.
---

View file

@ -0,0 +1,31 @@
---
layout: "guides"
page_title: "Secret Management - Guides"
sidebar_current: "guides-secret-mgmt"
description: |-
A very common use case of Vault is to manage your organization's secrets from
storing credentials and API keys to encrypting passwords for user signups.
Vault is meant to be a solution for all secret management needs.
---
# Secret Management
Vault is a tool for securely accessing secrets. A secret is anything that you
want to tightly control access to, such as API keys, passwords, certificates,
and more. Vault provides a unified interface to any secret while providing
tight access control and recording a detailed audit log.
Secret Management guides demonstrate features in Vault to securely store your
secrets.
- [Static Secrets](/guides/secret-mgmt/static-secrets.html) guide walks you
through the steps to write secrets in Vault, and control who can access them.
- [Secret as a Service: Dynamic Secrets](/guides/secret-mgmt/dynamic-secrets.html)
guide demonstrates the Vault feature to generate database credentials
on-demand so that each application or system can obtain its own credentials,
and its permissions can be tightly controlled.
- [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.

View file

@ -1,7 +1,7 @@
---
layout: "guides"
page_title: "Static Secrets - Guides"
sidebar_current: "guides-static-secrets"
sidebar_current: "guides-secret-mgmt-static-secrets"
description: |-
Vault supports generating new unseal keys as well as rotating the underlying
encryption keys. This guide covers rekeying and rotating Vault's encryption

View file

@ -3,50 +3,59 @@
<ul class="nav docs-sidenav">
<li<%= sidebar_current("guides-policy") %>>
<a href="/guides/policies.html">Policies</a>
<li<%= sidebar_current("getting-started")%>>
<a href="/guides/getting-started/index.html">Getting Started</a>
</li>
<li<%= sidebar_current("guides-authentication") %>>
<a href="/guides/authentication.html">AppRole Pull Authentication</a>
<li<%= sidebar_current("guides-operations")%>>
<a href="/guides/operations/index.html">Vault Operations</a>
<ul class="nav">
<li<%= sidebar_current("guides-operations-production-hardening") %>>
<a href="/guides/operations/production.html">Production Hardening</a>
</li>
<li<%= sidebar_current("guides-operations-replication") %>>
<a href="/guides/operations/replication.html">Replication Setup &amp; Guidance</a>
</li>
</ul>
</li>
<li<%= sidebar_current("guides-static-secrets") %>>
<a href="/guides/static-secrets.html">Static Secrets</a>
<li<%= sidebar_current("guides-configuration")%>>
<a href="/guides/configuration/index.html">Vault Configuration</a>
<ul class="nav">
<li<%= sidebar_current("guides-configuration-policies") %>>
<a href="/guides/configuration/policies.html">Policies</a>
</li>
<li<%= sidebar_current("guides-configuration-authentication") %>>
<a href="/guides/configuration/authentication.html">AppRole Pull Authentication</a>
</li>
<li<%= sidebar_current("guides-configuration-lease") %>>
<a href="/guides/configuration/lease.html">Tokens and Leases</a>
</li>
<li<%= sidebar_current("guides-configuration-generate-root") %>>
<a href="/guides/configuration/generate-root.html">Root Token Generation</a>
</li>
<li<%= sidebar_current("guides-configuration-rekeying-and-rotating") %>>
<a href="/guides/configuration/rekeying-and-rotating.html">Rekeying &amp; Rotating</a>
</li>
<li<%= sidebar_current("guides-configuration-plugin-backends") %>>
<a href="/guides/configuration/plugin-backends.html">Building Plugin Backends</a>
</li>
</ul>
</li>
<li<%= sidebar_current("guides-dynamic-secrets") %>>
<a href="/guides/dynamic-secrets.html">Secret as a Service</a>
</li>
<li<%= sidebar_current("guides-lease") %>>
<a href="/guides/lease.html">Tokens and Leases</a>
</li>
<li<%= sidebar_current("guides-cubbyhole") %>>
<a href="/guides/cubbyhole.html">Cubbyhole Response Wrapping</a>
</li>
<li<%= sidebar_current("guides-production-hardening") %>>
<a href="/guides/production.html">Production Hardening</a>
</li>
<li<%= sidebar_current("guides-generate-root") %>>
<a href="/guides/generate-root.html">Root Token Generation</a>
</li>
<li<%= sidebar_current("guides-rekeying-and-rotate") %>>
<a href="/guides/rekeying-and-rotating.html">Rekeying &amp; Rotating</a>
</li>
<li<%= sidebar_current("guides-replication") %>>
<a href="/guides/replication.html">Replication Setup &amp; Guidance</a>
</li>
<li<%= sidebar_current("guides-plugin-backends") %>>
<a href="/guides/plugin-backends.html">Building Plugin Backends</a>
<li<%= sidebar_current("guides-secret-mgmt")%>>
<a href="/guides/secret-mgmt/index.html">Secret Management</a>
<ul class="nav">
<li<%= sidebar_current("guides-secret-mgmt-static-secrets") %>>
<a href="/guides/secret-mgmt/static-secrets.html">Static Secrets</a>
</li>
<li<%= sidebar_current("guides-secret-mgmt-dataynamic-secrets") %>>
<a href="/guides/secret-mgmt/dynamic-secrets.html">Secret as a Service</a>
</li>
<li<%= sidebar_current("guides-secret-mgmt-cubbyhole") %>>
<a href="/guides/secret-mgmt/cubbyhole.html">Cubbyhole Response Wrapping</a>
</li>
</ul>
</li>
<hr>