Vault Policies

16min
Vault

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.

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 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

Open a terminal and start a Vault dev server with root as the root token.
```
$ vault server -dev -dev-root-token-id=root
```
The Vault dev server defaults to running at 127.0.0.1:8200. The server is also initialized and unsealed.
Insecure operation
Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.
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
```
Note
For these tasks, you can use Vault's root token. However, it is recommended that root tokens are only used for enough initial setup or in emergencies. As a best practice, use tokens with an appropriate set of policies based on your role in the organization.

The Vault server is ready.

Note

If you do not have access to an HCP Vault cluster, visit the Create a Vault Cluster on HCP tutorial.

Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the VAULT_ADDR environment variable to the copied address.
```
$ export VAULT_ADDR=<Public_Cluster_URL>
```
Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.

Type vault status to verify your connectivity to the Vault cluster.

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.9.2+ent
Storage Type             raft
...snipped...

The HCP Vault server is ready.

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

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.

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 Root protected endpoints section).

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

Note

The patch capability is introduced in Vault 1.9.0. To learn more, refer to the Versioned Key/Value Secrets Engine tutorial.

Create a policy

Create an admin policy

Create a policy named admin with the policy defined in admin-policy.hcl.

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

The policy is created or updated; if it already exists.

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 policy is created or updated; if it already exists.

$ 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" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       --request PUT \
       --data @payload.json \
       $VAULT_ADDR/v1/sys/policies/acl/admin

The policy is created or updated; if it already exists.

Display a policy

List all the policies.

$ vault policy list

Read the admin policy.

$ vault policy read admin

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

List all the policies.

Note

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

$ 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
}

Note

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

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

Read the admin policy.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
      --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
      $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 denying by all of its 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
s.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, 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
s.MdNlboI0nff3Xpo97d1TfIxd

The admin policy defines capabilities for the path sys/auth/*. Create a request payload containing the token and the path.

$ 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"

Output:

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

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

Retrieve the capabilities of this token for a path not defined in the policy.

First, create a request payload containing the token and the path (identity/entity).

$ 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"

Output:

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

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

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

Display the ADMIN_TOKEN.

$ echo $ADMIN_TOKEN
s.MdNlboI0nff3Xpo97d1TfIxd

The admin policy defines capabilities for the path sys/auth/*. Create a request payload containing the token and the path.

$ 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" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       --data @payload.json \
       $VAULT_ADDR/v1/sys/capabilities | jq ".data"

Output:

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

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

Retrieve the capabilities of this token for a path not defined in the policy.

First, create a request payload containing the token and the path (identity/entity).

$ 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" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       --data @payload.json \
       $VAULT_ADDR/v1/sys/capabilities | jq ".data"

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, 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, but displays the ACL policy needed to successfully execute the command.

Vault version

The -output-policy flag requires Vault 1.11 or later.

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"

Output:

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

Next, 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

Root protected API endpoints

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

Path	HTTP verb	Description
auth/token/accessors	LIST	List token accessor
auth/token/create-orphan	POST	Create an orphan token (the same as `no_parent` option)
auth/token	POST	Create a periodic or an orphan token (`period` or `no_parent`) option
pki/root	DELETE	Delete the current CA key (pki secrets engine)
pki/root/sign-self-issued	POST	Use the configured CA certificate to sign a self-issued certificate (pki secrets engine)
sys/audit	GET	List enabled audit devices
sys/audit/:path	PUT, DELETE	Enable or remove an audit device
sys/auth/:path	GET, POST, DELETE	Manage the auth methods (enable, read, delete, and tune)
sys/config/auditing/request-headers	GET	List the request headers that are configured to be audited
sys/config/auditing/request-headers:name	GET, PUT, DELETE	Manage the auditing headers (create, update, read and delete)
sys/config/cors	GET, PUT, DELETE	Configure CORS setting
sys/config-ui	GET	Configure the UI settings
sys/internal/specs/openapi	GET	Generate an OpenAPI document of the mounted backends
sys/leases/lookup/:prefix	LIST	List lease IDs
sys/leases/revoke-force/:prefix	PUT	Revoke all secrets or tokens ignoring backend errors
sys/leases/revoke-prefix/:prefix	PUT	Revoke all secrets generated under a given prefix
sys/plugins/catalog/:type/:name	GET, PUT, DELETE	Register a new plugin, or read/remove an existing plugin
sys/raw	LIST, GET	Returns a list of keys for a given path prefix
sys/replication/reindex	POST	Reindex the local data storage
sys/replication/performance/primary/secondary-token	POST	Generate a performance secondary activation token
sys/replication/dr/primary/secondary-token	POST	Generate a DR secondary activation token
sys/rotate	PUT	Trigger a rotation of the backend encryption key
sys/seal	PUT	Seals the Vault
sys/step-down	PUT	Forces the node to give up active status

Help and reference

Policies documentation
Policy API documentation

Back to Collection