Access controls with Vault policies

15min
|
Vault
Interactive

Deployment

Vault uses policies to govern the behavior of clients and instrument Role-Based Access Control (RBAC) by specifying access privileges (authorization). The Vault RBAC system allows you to follow common industry identity and access management practices. Following practices such as the principle of least privilege, ensures that clients have only the permissions they need to perform their tasks.

Vault creates a root policy during initialization. The root policy, attached to the root token when server initialization completes, is capable of performing every operation for all paths. The root token, with the root policy, 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 allowed capabilities. You must define capabilities for a path, as Vault defaults to denying capabilities to paths to ensure that it is secure by default.

HashiCorp Configuration Language (HCL)

You write Vault Access Control List (ACL) policies in HCL (HCL) or JSON format.

Sentinel is another policy framework available in Vault Enterprise. Since Sentinel is an enterprise-only feature, this tutorial focuses on writing ACL policies.

Note

To learn more about Sentinel policies in Vault, refer to the Sentinel policies tutorial.

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 the root policy, and write fine-grained policies to follow the practice of least privilege. For example, if an app gets AWS credentials from Vault, write a policy that grants read from AWS secrets engine, but not delete.

Vault attaches policies to a token, enforcing client permissions in Vault.

Prerequisites

Vault installed.
jq for consuming Vault JSON formatted output and capturing specific fields.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Set up the lab

Open a terminal and start a Vault dev server with root as the root token.
```
$ vault server -dev -dev-root-token-id=root
```
The dev server listens on the loopback interface at 127.0.0.1 on TCP port 8200 with TLS enabled. At runtime, the dev server also automatically unseals, and prints the unseal key and initial root token values to the standard output.
In a new terminal, export an environment variable for the vault CLI to address the Vault server.
```
$ export VAULT_ADDR=http://127.0.0.1:8200
```
Export an environment variable for the vault CLI to authenticate with the Vault server.
```
$ export VAULT_TOKEN=root
```

The Vault server is ready.

Anatomy of a Vault policy

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

Capability	Associated HTTP verbs
create	POST/PUT
read	GET
update	POST/PUT
delete	DELETE
list	LIST
patch	PATCH
sudo	-
deny	-

The sudo capability allows access to paths that are root-protected (Refer to the list of root-protected API endpoints in the Vault documentation).

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

The path includes the location of the mounted plugin, such as a secret engine mounted at secret/, and the path to the resource, such as database/credentials.

This policy grants the read capability to the path secret/database/credentials.

path "secret/database/credentials" {
  capabilities = ["read"]
}

Write a policy

Before writing a policy, you must first collect the requirements needed by the Vault entity using the policy.

For example, your Vault administrators need to manage Vault. While the root policy provides full access to Vault, it is not recommended to use it for day-to-day operations. Instead, you should create a policy that allows your Vault administrators to manage Vault.

The Vault administrator 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

(Optional) Use the vault policy fmt command to format the policy file. This command ensures proper formatting and indentation of the policy file.
```
$ vault policy fmt admin-policy.hcl
Success! Formatted policy: admin-policy.hcl
```

Create a policy

You can create policies using the Vault CLI, API, or UI.

Use the vault policy write command to create a policy named admin with the policy defined in admin-policy.hcl file.
```
$ vault policy write admin admin-policy.hcl
Success! Uploaded policy: admin
```
The command creates or updates the policy if it already exists.

Use the vault policy read command view the newly created policy.

$ vault policy read admin

Read system health check
path "sys/health" {
  capabilities = ["read", "sudo"]
}

# Create and manage ACL policies broadly across Vault
...snip...

The output displays the paths and capabilities defined for this policy.

Create a request payload containing the stringified admin policy.

$ tee payload.json <<EOF
{
  "policy": "# Manage auth methods broadly across Vault\npath \"auth/*\"\n{\n  capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# Create, update, and delete auth methods\npath \"sys/auth/*\"\n{\n  capabilities = [\"create\", \"update\", \"delete\", \"sudo\"]\n}\n\n# List auth methods\npath \"sys/auth\"\n{\n  capabilities = [\"read\"]\n}\n\n# List existing policies\npath \"sys/policies/acl\"\n{\n  capabilities = [\"list\"]\n}\n\n# Create and manage ACL policies \npath \"sys/policies/acl/*\"\n{\n  capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# List, create, update, and delete key/value secrets\npath \"secret/*\"\n{\n  capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# Manage secrets engines\npath \"sys/mounts/*\"\n{\n  capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# List existing secrets engines.\npath \"sys/mounts\"\n{\n  capabilities = [\"read\"]\n}\n\n# Read health checks\npath \"sys/health\"\n{\n  capabilities = [\"read\", \"sudo\"]\n}"
}
EOF

Create a policy named admin

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request PUT \
       --data @payload.json \
       $VAULT_ADDR/v1/sys/policies/acl/admin

The API creates or updates the policy if it already exists.

Open a web browser and launch the Vault UI (for example, http://127.0.0.1:8200/ui) and enter root in the Token text field.
Click Sign In.
Click the Policies tab, and then select Create ACL policy.
Toggle the Upload file sliding switch, and click Choose a file to select your admin-policy.hcl file you authored. Set the Name to admin.
Click Create Policy to complete.
Tip
You can review an example policy by clicking the example template link under the Policy text box.

Display a policy

You can list all policies available in Vault, or read a specific policy.

List all the policies.
```
$ vault policy list
admin
default
root
```
The output displays the names of all policies defined in Vault.

Read the admin policy.

$ vault policy read admin
Read system health check
path "sys/health" {
  capabilities = ["read", "sudo"]
}

# Create and manage ACL policies broadly across Vault
...snip...

The output displays the paths and capabilities defined for this policy.

Note

This section uses jq to process the JSON output for readability.

List all the policies.

$ curl --request LIST \
      --header "X-Vault-Token: $VAULT_TOKEN" \
      $VAULT_ADDR/v1/sys/policies/acl | jq

Read the admin policy.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
      $VAULT_ADDR/v1/sys/policies/acl/admin | jq

Example output:

{
  "request_id": "3f826e5c-70a0-2998-8082-fe34c67c59d1",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "name": "admin",
    "policy": "# Manage auth methods broadly across Vault\npath \"auth/*\"\n{\n  capabilities = [\"create\", \"read\" ...
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Check token capabilities

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

Create a token with the admin policy attached and store the token in the variable ADMIN_TOKEN.

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

Display the ADMIN_TOKEN.
```
$ echo $ADMIN_TOKEN
hvs.MdNlboI0nff3Xpo97d1TfIxd
```
The admin policy defines capabilities for the path sys/auth/*.
Retrieve the capabilities of this token for the sys/auth/approle path.
```
$ vault token capabilities $ADMIN_TOKEN sys/auth/approle
create, delete, read, sudo, update
```
The output displays that this token has create, delete, read, sudo, and update capabilities for this path.
Retrieve the capabilities of this token for a path not defined in the policy.
```
$ vault token capabilities $ADMIN_TOKEN identity/entity
deny
```
The output displays that this token has no capabilities (deny) for this path.

Create a token with the admin policy attached and store the token in the variable ADMIN_TOKEN.

$ ADMIN_TOKEN=$(curl --request POST --header "X-Vault-Token: $VAULT_TOKEN" \
       --data '{ "policies":"admin" }' \
       $VAULT_ADDR/v1/auth/token/create | jq -r ".auth.client_token")

Display the ADMIN_TOKEN.

$ echo $ADMIN_TOKEN
hvs.MdNlboI0nff3Xpo97d1TfIxd

Create a request payload containing the token and the path sys/auth/*.

$ tee payload.json <<EOF
{
  "token": "$ADMIN_TOKEN",
  "path": "sys/auth/approle"
}
EOF

Retrieve the capabilities of this token for the sys/auth/approle path.

$ curl --request POST --header "X-Vault-Token: $VAULT_TOKEN" \
       --data @payload.json \
       $VAULT_ADDR/v1/sys/capabilities | jq ".data"

Example output:

{
  "capabilities": [
    "create",
    "delete",
    "sudo",
    "update"
  ],
  "sys/auth/approle": [
    "create",
    "delete",
    "sudo",
    "update"
  ]
}

The output displays that this token has create, delete, read, sudo, and update capabilities for this path.

Create a request payload to retrieve the capabilities of this token for a path not defined in the policy.
```
$ tee payload.json <<EOF
{
  "token": "$ADMIN_TOKEN",
  "path": "identity/entity"
}
EOF
```

Retrieve the capabilities of this token for the identity/entity path.

$ curl --request POST --header "X-Vault-Token: $VAULT_TOKEN" \
       --data @payload.json \
       $VAULT_ADDR/v1/sys/capabilities | jq ".data"

Example output:

{
  "capabilities": [
    "deny"
  ],
  "identity/entity": [
    "deny"
  ]
}

The output displays that this token has no capabilities (deny) for this path.

Click the Vault CLI shell icon (>_) to open a command shell. Create a token with the admin policy attached.
```
$ vault write auth/token/create policies=admin
```
Retrieve the capabilities of this token for the sys/auth/approle path using the sys/capabilities endpoint.
The output displays that this token has create, delete, read, sudo, and update capabilities for this path.
Retrieve the capabilities of this token for a path not defined in the policy.
Example:
```
$ vault write sys/capabilities token=<token> path="identity/entity"
```
The output displays that this token has no capabilities (deny) for this path.
Click the icon (>_) again to hide the shell.

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.

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"

Example output:

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

Check the policy needed for kv get:
```
$ vault kv get -output-policy -mount=secret customer/acme
path "secret/data/customer/acme" {
  capabilities = ["read"]
}
```
This example indicates that the vault kv put and vault kv get operations require read, create, and update capabilities on the secret/data/customer/acme path.
If you are unfamiliar with kv get, kv put, or the options, refer to Versioned Key/Value Secrets Engine

Help and reference

Introduction to Vault Policies documentation
Policies documentation
Policy API documentation

Collection Overview

Policies

Write a policy using API documentation