Vault Policies
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 is capable of performing every operation for all paths. This policy is assigned to the root token that displays when initialization completes. This 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 capabilities that are allowed. Capabilities for a path must be granted, as Vault defaults to denying capabilities to paths to ensure that it is secure by default.
HashiCorp Configuration Language (HCL)
Policies written in HCL format are often referred as ACL Policies. (NOTE: HCL is JSON compatible; therefore JSON can be used as completely valid input.) Sentinel is another framework for policy which is available in Vault Enterprise. Since Sentinel is an enterprise-only feature, this tutorial focuses on writing ACL policies as a foundation.
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 root policy, and write fine-grained policies to practice
least privileged. For example, if an app gets AWS credentials from Vault,
write policy grants to read
from AWS secrets engine but not to delete
, etc.
Policies are attached to tokens and roles to enforce client permissions on Vault.
Prerequisites
To perform the tasks described in this tutorial, you need to have a Vault environment. Refer to the Getting Started tutorial to install Vault. Make sure that your Vault server has been initialized and unsealed.
Lab setup
Open a terminal and start a Vault dev server with
root
as the root token.The Vault dev server defaults to running at
127.0.0.1:8200
. The server is also initialized and unsealed.Insecure operation
Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.
Export an environment variable for the
vault
CLI to address the Vault server.Export an environment variable for the
vault
CLI to authenticate with the Vault server.Note
For these tasks, you can use Vault's root token. However, it is recommended that root tokens are only used for enough initial setup or in emergencies. As a best practice, use tokens with an appropriate set of policies based on your role in the organization.
The Vault server is ready.
Write a policy
The first step to create gather policy requirements.
An admin user 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
.
A policy define 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 Root protected endpoints section).
The deny capability disables access to the path. When combined with other capabilities it always precedence.
Note
The patch
capability is introduced in Vault 1.9.0. To learn
more, refer to the Versioned Key/Value Secrets
Engine tutorial.
Create a policy
Create an admin policy
Create a policy named admin
with the policy defined in admin-policy.hcl
.
The policy is created or updated; if it already exists.
Display a policy
List all the policies.
Read the admin
policy.
The output displays the paths and capabilities defined for this policy.
Check token capabilities
A token is able to display its capabilities for a path. This provides a way to verify the capabilities granted or denying by all of its attached policies.
Create a token with the admin
policy attached and store the token in the
variable ADMIN_TOKEN
.
Display the ADMIN_TOKEN
.
The admin policy defines capabilities for the path sys/auth/*
.
Retrieve the capabilities of this token for the sys/auth/approle
path.
The output displays that this token has create, delete, read, sudo, update capabilities for this path.
Retrieve the capabilities of this token for a path not defined in the policy.
The output displays that this token has no capabilities (deny
) for this path.
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, but displays the
ACL policy needed to successfully execute the command.
Vault version
The -output-policy
flag requires Vault 1.11 or later.
First, check the policy needed for a
kv put
:Output:
Next, check the policy needed for
kv get
:
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
Root protected API endpoints
The following paths requires a root token or sudo
capability in the policy:
Path | HTTP verb | Description |
---|---|---|
auth/token/accessors | LIST | List token accessor |
auth/token/create-orphan | POST | Create an orphan token (the same as no_parent option) |
auth/token | POST | Create a periodic or an orphan token (period or no_parent ) option |
pki/root | DELETE | Delete the current CA key (pki secrets engine) |
pki/root/sign-self-issued | POST | Use the configured CA certificate to sign a self-issued certificate (pki secrets engine) |
sys/audit | GET | List enabled audit devices |
sys/audit/:path | PUT, DELETE | Enable or remove an audit device |
sys/auth/:path | GET, POST, DELETE | Manage the auth methods (enable, read, delete, and tune) |
sys/config/auditing/request-headers | GET | List the request headers that are configured to be audited |
sys/config/auditing/request-headers:name | GET, PUT, DELETE | Manage the auditing headers (create, update, read and delete) |
sys/config/cors | GET, PUT, DELETE | Configure CORS setting |
sys/config-ui | GET | Configure the UI settings |
sys/internal/specs/openapi | GET | Generate an OpenAPI document of the mounted backends |
sys/leases/lookup/:prefix | LIST | List lease IDs |
sys/leases/revoke-force/:prefix | PUT | Revoke all secrets or tokens ignoring backend errors |
sys/leases/revoke-prefix/:prefix | PUT | Revoke all secrets generated under a given prefix |
sys/plugins/catalog/:type/:name | GET, PUT, DELETE | Register a new plugin, or read/remove an existing plugin |
sys/raw | LIST, GET | Returns a list of keys for a given path prefix |
sys/replication/reindex | POST | Reindex the local data storage |
sys/replication/performance/primary/secondary-token | POST | Generate a performance secondary activation token |
sys/replication/dr/primary/secondary-token | POST | Generate a DR secondary activation token |
sys/rotate | PUT | Trigger a rotation of the backend encryption key |
sys/seal | PUT | Seals the Vault |
sys/step-down | PUT | Forces the node to give up active status |
Help and reference
- Policies documentation
- Policy API documentation