Access controls with Vault policies

15min
|
Vault

Deployment

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

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

Set up the lab

Note

If you do not have access to an HCP Vault Dedicated 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>

$ export VAULT_ADDR=<Public_Cluster_URL>

Return to the Overview page and click Generate token.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=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...

$ 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 Vault Dedicated 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"]
}

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

$ 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

$ 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
```
```
$ 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...

$ 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

$ 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

$ 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 API creates or updates the policy if it already exists.

Open a web browser and launch the Vault UI (e.g. 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 textbox.

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

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

$ 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" \
      --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
      $VAULT_ADDR/v1/sys/policies/acl | jq

$ 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

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

{
  "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")

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

Display the ADMIN_TOKEN.

$ echo $ADMIN_TOKEN
hvs.MdNlboI0nff3Xpo97d1TfIxd

$ 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

$ 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
```
```
$ 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" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       --data '{ "policies":"admin" }' \
       $VAULT_ADDR/v1/auth/token/create | jq -r ".auth.client_token")

$ 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
hvs.MdNlboI0nff3Xpo97d1TfIxd

$ 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

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

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

Example output:

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

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

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

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

Example output:

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

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

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

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"]
}
```
```
$ 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

Policies documentation
Policy API documentation

Collection Overview

Policies

Write a policy using API documentation