Create Vault policies

6min
|
HCP
Vault

Policies are a declarative way to grant or forbid access to certain paths and operations in Vault. In this tutorial, you will create a policy and then edit it to support new requirements.

Note

This step assumes that you created and connected to the HCP Vault Dedicated cluster in the Create a Vault Cluster on HashiCorp Cloud Platform (HCP) step.

Create a policy

ACL policies are authored in HashiCorp Configuration Language (HCL). Here is an example policy:

# Grant 'create', 'read' and 'update' permission to paths prefixed by 'secret/data/test/'
path "secret/data/test/*" {
  capabilities = [ "create", "read", "update" ]
}

# Manage namespaces
path "sys/namespaces/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
}

The policy format uses a prefix matching system on the API path to determine access control. The most specific defined policy is used, either an exact match or the longest-prefix glob match. Since everything in Vault must be accessed via the API, this gives strict control over every aspect of Vault, including enabling secrets engines, enabling auth methods, authenticating, as well as secret access.

Important

Policies are tied to their namespace. When you create a policy in the admin/ namespace, the policy is only available in the admin/ namespace. This is to keep each namespace isolated and secure.

Warning

There are two out-of-the-box policies in the admin/ namespace: default and hcp-root. Do NOT edit the hcp-root policy. The admin token generated by the HCP portal has the hcp-root policy attached granting permissions necessary for initial setup. Modifying this policy could deny you from performing the admin tasks you desire.

In the Vault UI, set the current namespace to admin/.
Click Policies.
Select Create ACL policy.
Enter tester in the Name field.

Enter the following policy in the Policy textbox.

# Grant 'create', 'read' and 'update' permission to paths prefixed by 'secret/data/test/'
path "secret/data/test/*" {
  capabilities = [ "create", "read", "update" ]
}

# Manage namespaces
path "sys/namespaces/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
}

Tip

You can review an example policy by clicking the example template link under the Policy textbox.

Click Create policy at the bottom of the page.
The policy is created and this view displays its name and contents.

If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```

To write a policy, use vault policy write command. Review the command help.

$ vault policy write -h

Usage: vault policy write [options] NAME PATH

  Uploads a policy with name NAME from the contents of a local file PATH or
  stdin. If PATH is "-", the policy is read from stdin. Otherwise, it is
  loaded from the file at the given path on the local disk.

  Upload a policy named "my-policy" from "/tmp/policy.hcl" on the local disk:

      $ vault policy write my-policy /tmp/policy.hcl

  Upload a policy from stdin:

      $ cat my-policy.hcl | vault policy write my-policy -

   ...snip...

Create the policy named tester with the contents from stdin.

$ vault policy write tester - << EOF
# Grant 'create', 'read' and 'update' permission to paths prefixed by 'secret/data/test/'
path "secret/data/test/*" {
  capabilities = [ "create", "read", "update" ]
}

# Manage namespaces
path "sys/namespaces/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
}
EOF

Successful output example:

Success! Uploaded policy: tester

List all the policies.

$ vault policy list
default
hcp-root
tester

View the contents of the tester policy.

$ vault policy read tester
# Grant 'create', 'read' and 'update' permission to paths prefixed by 'secret/data/test/'
path "secret/data/test/*" {
  capabilities = [ "create", "read", "update" ]
}

# Manage namespaces
path "sys/namespaces/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
}

If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Create a request payload containing the stringified tester policy.

$ tee payload-policy.json <<EOF
{
  "policy": "# Grant 'create' and 'update' permission to paths prefixed by 'secret/data/test/'\npath \"secret/data/test/*\" {\n  capabilities = [ \"create\", \"read\", \"update\" ]\n}\n\n# Manage namespaces\npath \"sys/namespaces/*\" {\n   capabilities = [ \"create\", \"read\", \"update\", \"delete\", \"list\" ]\n}\n"
}
EOF

Create a poilcy named, "tester".

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

List existing policies in the target namespace.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin" \
    --request LIST \
    --data @payload-policy.json \
    $VAULT_ADDR/v1/sys/policies/acl | jq -r ".data.keys"

Output:

["default", "hcp-root", "tester"]

Read back the tester policy.

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

Output:

{
  "name": "tester",
  "policy": "# Grant 'create' and 'update' permission to paths prefixed by 'secret/data/test/'\npath \"secret/data/test/*\" {\n  capabilities = [ \"create\", \"read\", \"update\" ]\n}\n\n# Manage namespaces\npath \"sys/namespaces/*\" {\n   capabilities = [ \"create\", \"read\", \"update\", \"delete\", \"list\" ]\n}\n"
}

Policies to access another namespace

The policy path is relative to the namespace on which the policy is deployed. If you want to access the database/ path in the admin/education/training namespace from the admin namespace, the policy path must be education/training/database/*.

The policy you deploy on the admin namespace must look similar to the following:

# Grant CRUD operations against the path prefixed with 'database/' in the 'training' namespace
path "education/training/database/*" {
   capabilities = [ "create", "read", "update", "delete" ]
}

The equivalent policy you deploy onto the admin/education namespace must look as follows:

# Grant CRUD operations against the path prefixed with 'database/' in the 'training' namespace
path "training/database/*" {
   capabilities = [ "create", "read", "update", "delete" ]
}

To learn more, read to the Secure Multi-Tenancy with Namespaces tutorial.

Help and reference

You created a policy in Vault. Policies are attached to tokens that Vault generates through its various authentication methods.

You created a policy from a file. Policy authoring requires the understanding of paths which map to the Vault API endpoints, and the available actions for each path. Learn more about policies.

In addition to ACL policies, HCP Vault Dedicated Plus tier also supports Sentinel policies to enable fine-grained, logic-based policy decisions.