Vault Policies

Vault uses policies to govern the behavior of clients and instrument Role-Based Access Control (RBAC) by specifying access privileges (authorization).

Vault creates a root policy during initialization. The root policy is capable of performing every operation for all paths. This policy is assigned to the root token that displays when initialization completes. This provides an initial superuser to enable secrets engines, define policies, and configure authentication methods.

Vault also creates a default, policy. The default policy defines a common set of capabilities that enable a token the ability to reflect and manage itself. This policy is also assigned to the root token.

A policy defines a list of paths. Each path expresses the capabilities that are allowed. Capabilities for a path must be granted, as Vault defaults to denying capabilities to paths to ensure that it is secure by default.

»HashiCorp Configuration Language (HCL)

Policies written in HCL format are often referred as ACL Policies. (NOTE: HCL is JSON compatible; therefore JSON can be used as completely valid input.) Sentinel is another framework for policy which is available in Vault Enterprise. Since Sentinel is an enterprise-only feature, this tutorial focuses on writing ACL policies as a foundation.

»Challenge

Since Vault centrally secures, stores, and controls access to secrets across distributed infrastructure and applications, it is critical to control permissions before any user or machine can gain access.

»Solution

Restrict the use of root policy, and write fine-grained policies to practice least privileged. For example, if an app gets AWS credentials from Vault, write policy grants to read from AWS secrets engine but not to delete, etc.

Policies are attached to tokens and roles to enforce client permissions on Vault.

»Prerequisites

To perform the tasks described in this tutorial, you need to have a Vault environment. Refer to the Getting Started tutorial to install Vault. Make sure that your Vault server has been initialized and unsealed.

»Lab setup

$ vault server -dev -dev-root-token-id=root

$ vault server -dev -dev-root-token-id=root

$ export VAULT_ADDR=http://127.0.0.1:8200

$ export VAULT_ADDR=http://127.0.0.1:8200

$ export VAULT_TOKEN=root

$ export VAULT_TOKEN=root

»Write a policy

The first step to create gather policy requirements.

An admin user must be able to:

• Read system health check
• Create and manage ACL policies broadly across Vault
• Enable and manage authentication methods broadly across Vault
• Manage the Key-Value secrets engine enabled at secret/ path

Define the admin policy in the file named admin-policy.hcl.

$ tee admin-policy.hcl <<EOF
# Read system health check
path "sys/health"
{
  capabilities = ["read", "sudo"]
}

# Create and manage ACL policies broadly across Vault

# List existing policies
path "sys/policies/acl"
{
  capabilities = ["list"]
}

# Create and manage ACL policies
path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# Enable and manage authentication methods broadly across Vault

# Manage auth methods broadly across Vault
path "auth/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# Create, update, and delete auth methods
path "sys/auth/*"
{
  capabilities = ["create", "update", "delete", "sudo"]
}

# List auth methods
path "sys/auth"
{
  capabilities = ["read"]
}

# Enable and manage the key/value secrets engine at `secret/` path

# List, create, update, and delete key/value secrets
path "secret/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# Manage secrets engines
path "sys/mounts/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# List existing secrets engines.
path "sys/mounts"
{
  capabilities = ["read"]
}
EOF

$ tee admin-policy.hcl <<EOF
# Read system health check
path "sys/health"
{
  capabilities = ["read", "sudo"]
}

# Create and manage ACL policies broadly across Vault

# List existing policies
path "sys/policies/acl"
{
  capabilities = ["list"]
}

# Create and manage ACL policies
path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# Enable and manage authentication methods broadly across Vault

# Manage auth methods broadly across Vault
path "auth/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# Create, update, and delete auth methods
path "sys/auth/*"
{
  capabilities = ["create", "update", "delete", "sudo"]
}

# List auth methods
path "sys/auth"
{
  capabilities = ["read"]
}

# Enable and manage the key/value secrets engine at `secret/` path

# List, create, update, and delete key/value secrets
path "secret/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# Manage secrets engines
path "sys/mounts/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# List existing secrets engines.
path "sys/mounts"
{
  capabilities = ["read"]
}
EOF

A policy define one or more paths and a list of permitted capabilities. Most of these capabilities map to the HTTP verbs supported by the Vault API.

The sudo capability allows access to paths that are root-protected (Refer to the Root protected endpoints section).

The deny capability disables access to the path. When combined with other capabilities it always precedence.

»Create a policy

Create an admin policy

$ vault policy write admin admin-policy.hcl
Success! Uploaded policy: admin

$ vault policy write admin admin-policy.hcl
Success! Uploaded policy: admin

»Display a policy

$ vault policy list

$ vault policy list

$ vault policy read admin

$ vault policy read admin

»Check token capabilities

A token is able to display its capabilities for a path. This provides a way to verify the capabilities granted or denying by all of its attached policies.

$ ADMIN_TOKEN=$(vault token create -format=json -policy="admin" | jq -r ".auth.client_token")

$ ADMIN_TOKEN=$(vault token create -format=json -policy="admin" | jq -r ".auth.client_token")

$ echo $ADMIN_TOKEN
s.MdNlboI0nff3Xpo97d1TfIxd

$ echo $ADMIN_TOKEN
s.MdNlboI0nff3Xpo97d1TfIxd

$ vault token capabilities $ADMIN_TOKEN sys/auth/approle
create, delete, read, sudo, update

$ vault token capabilities $ADMIN_TOKEN sys/auth/approle
create, delete, read, sudo, update

$ vault token capabilities $ADMIN_TOKEN identity/entity
deny

$ vault token capabilities $ADMIN_TOKEN identity/entity
deny

»Determine necessary ACL policy from Vault commands

Adding the -output-policy flag prints the ACL policy needed to run a command.
Adding this flag to a command does not execute the command, but displays the ACL policy needed to successfully execute the command.

1. First, check the policy needed for a kv put:

   $ vault kv put -output-policy -mount=secret customer/acme customer_name="ACME Inc." \
       contact_email="john.smith@acme.com"
   

   $ vault kv put -output-policy -mount=secret customer/acme customer_name="ACME Inc." \
       contact_email="john.smith@acme.com"
   

   Copy

   Output:

   path "secret/data/customer/acme" {
     capabilities = ["create", "update"]
   }
   

   path "secret/data/customer/acme" {
     capabilities = ["create", "update"]
   }
   

2. Next, check the policy needed for kv get:

   $ vault kv get -output-policy -mount=secret customer/acme
   path "secret/data/customer/acme" {
     capabilities = ["read"]
   }
   

   $ vault kv get -output-policy -mount=secret customer/acme
   path "secret/data/customer/acme" {
     capabilities = ["read"]
   }
   

   Copy

At a minimum that the policy for "secret*" must include read, create, update.

If you are unfamiliar with kv get, kv put or the options refer to Versioned Key/Value Secrets Engine

»Root protected API endpoints

The following paths requires a root token or sudo capability in the policy:

»Help and reference

• Policies documentation
• Policy API documentation