Manage access to secrets in HCP Vault Dedicated using 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

You write ACL policies using the 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 takes precedence, either an exact match or the longest-prefix glob match. Since everything in Vault uses the Vault API, this gives strict control over every aspect of Vault, including enabling secrets engines, enabling auth methods, authenticating, as well as secret access.

Important

You create policies in a namespace. When you create a policy in the admin/ namespace, the policy is only available in the admin/ namespace. This keeps 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 can prevent you from performing admin tasks.

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.
Vault displays the policy 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 the 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 policy 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"

Example output:

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

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

Example 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 in which you create the policy. 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 in 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 policy you deploy in the admin/education namespace must look similar to the following:

# 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 the Secure Multi-Tenancy with Namespaces tutorial.

Summary

You created a policy in Vault. Vault attaches policies to tokens that Vault generates through its various authentication methods.

You created a policy from a file. Policy authoring requires an 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.

Create and store secrets

Authenticate users