Create Vault Policies

6min
HCP
Vault

Policies provide 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 cluster in the Create a Vault Cluster on HashiCorp Cloud Platform (HCP) step.

Create a policy

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/.
Select Policies.
Select the Create ACL policy action.
Enter tester in the Name field.
Enter the following policy in the Policy field.

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

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

You can also refer to the Create Vault Policies tutorial.

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.

Next steps

You created a policy in Vault. Policies are attached to tokens that Vault generates through its various authentication methods. Learn how to manage authentication methods with Vault UI.

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.