Introduction
In HCP Vault, each Vault cluster has an admin namespace configured by the platform by default when the cluster is created. The root namespace is not accessible in HCP Vault - more information on this can be found here. To initially access the admin namespace in HCP Vault, you will need to generate an admin token via HCP. The default admin namespace name is not currently configurable and unfortunately, we do not have any information on if/when this may change. Operators can create namespaces within the admin namespace as needed to suit their operational needs.
For more information on the HCP Vault admin namespace, read more about HCP Namespace Considerations.
Use Case
Namespaces are a key part of how we balance both security and operability with HCP Vault. When a new cluster is bootstrapped, the platform uses the initial root token to generate an MSP token and then revokes the initial root token. The MSP token has very limited permissions at the root namespace, but does not have access to the admin namespace, and thus cannot access customer data.
Additionally, by limiting changes to the config at the root namespace, we prevent a lot of failure potential that might be inadvertently induced. A subset of functionality that would otherwise be accessed via the root namespace is provided via the HCP portal. More information on the MSP policy can be found here.
CLI and API requests to HCP Vault
All CLI and API requests to an HCP Vault cluster must include a Namespace in the request.
If using the Vault CLI:
Make sure the VAULT_NAMESPACE environment variable is set to “admin” (export VAULT_NAMESPACE=admin) or to a valid namespace within admin/
If a namespace is not set, Vault CLI will send requests to the root namespace by default which is not accessible in HCP Vault and you may receive a permission denied error.
~ ❯ env | grep VAULT
VAULT_TOKEN=<REDACTED>
VAULT_ADDR=https://vault-cluster.vault.def84aba-3536-4894-a627-6d7ed3acc5ff.aws.hashicorp.cloud:8200
~ ❯ export VAULT_NAMESPACE=admin
~ ❯ vault auth enable aws
Success! Enabled aws auth method at: aws/
You can also pass the namespace as a parameter using the Vault CLI as seen below
~ ❯ vault auth enable -ns=admin aws
Success! Enabled aws auth method at: aws/
If using the API directly:
Set a "X-Vault-Namespace: <namespace>" HTTP header for the request as seen in the example below. On login API requests to HCP Vault, if the Vault Namespace is not included in the request or the request path is invalid you may receive a {"errors":["permission denied"]}
Example with namespace header
curl \
--request POST \
--header "X-Vault-Namespace: admin" \
--data @payload.json \
"$VAULT_ADDR/v1/auth/userpass/login/testuser"
Example without namespace header
curl \
--request POST \
--header "X-Vault-Namespace: admin" \
--data @payload.json \
"$VAULT_ADDR/v1/auth/userpass/login/testuser"
{"errors":["permission denied"]}
Additional Links
Secure Multi-tenacity with Namespaces Learn Guide