Write policies using API documentation

Every Vault operation performed through the command-line interface (CLI), API, or web UI require that the authenticated client is granted access; access defined through policies. Everything in Vault is stored at different paths, like a filesystem, and every action in Vault has a corresponding path and capability. Policies provide a declarative way to grant or forbid access to paths and the capabilites at each path.

In this tutorial, you will learn Vault's policy language and how to translate API documentation to policies.

Define a policy

A policy is expressed in HashiCorp Configuration Language (HCL) and is composed of zero or more paths. Each path is expressed with the path keyword followed by the absolute path, expressed as a string, and a stanza that defines the capabilities and other configuration.

Given a KV-V2 secrets engine mounted at the path external-apis and a secret defined at /external-apis/data/socials/twitter.

Read a secret

Define a policy that grants the capability to read the secret at path /external-apis/data/socials/twitter.

path "/external-apis/data/socials/twitter" {
  capabilities = ["read"]
}

The path /external-apis/data/socials/twitter references an absolute path to a secret or configuration within the enabled secrets engine. The read capability grants access to read the data at the given path.

These paths and capabilities are entirely dependent on the secrets engine or endpoint. Each endpoint describes these details in the Vault API documentation.

Read the Read Secret Version section of the KV-V2 API documention.

The API documentation focuses on clients programatic interaction with Vault. To use this resource to define Vault policies requires translation.

The Method defines the HTTP verb GET. These HTTP verbs map closely, but not perfectly, to policy capabilities. The HTTP verb GET translates to the read capability.

The Path defines the path /secret/data/:path?version=:version-number.

The first element of the path secret, represents where the secrets engine is mounted. The documentation uses the default or common mount path for a secrets engine. The secret element translates to external-apis.

The /data element is static for secrets for this secrets engine.

The :path and :version-number elements represent parameters, or variables, that are substituted for specific values in a request. Parameters are prefaced with colon (:). The :path element translates to socials/twitter.

Create a secret

Read the Create/Update Secret section of the KV-V2 API documention.

Define a policy that grants the capability to create and update a secret at the /external-apis/data/socials/twitter path.

path "/external-apis/data/socials/twitter" {
  capabilities = ["create"]
}

The create capability grants the capability to create and update the secret at the given path. This capability creates a new secret, if not present, or updates an existing secret.

Create and read a secret

One or more policies can be expressed in the same policy definition.

Define a policy that grants the capability to create, update, and read a secret at the /external-apis/data/socials/twitter path.

path "/external-apis/data/socials/twitter" {
  capabilities = ["read"]
}

path "/external-apis/data/socials/twitter" {
  capabilities = ["create"]
}

This policy expresses two capabilities for the same path. Multiple capabilities for the same path can be expressed together.

Define a succint policy that grants the capability to create, update, and read a secret at the /external-apis/data/socials/twitter path.

path "/external-apis/data/socials/twitter" {
  capabilities = ["read", "create"]
}

Delete and undelete a secret

Read the Delete Latest Version of Secret and Undelete Secret Versions section of the KV-V2 API documention.

Challenge

Define a policy that grants the capability to delete and undelete secret at the /external-apis/data/socials/twitter path.

path "/external-apis/data/socials/twitter" {
  capabilities = ["delete"]
}

path "/external-apis/undelete/socials/twitter" {
  capabilities = ["update"]
}

Next steps

To define policies requires understanding the paths and capabilities of each authentication method and secrets engine. In this tutorial, you translated the API documentation into policies. Learn additional approaches in the Write a Policy from Audit Logs tutorial.