Enable multi-tenancy in HCP Vault with namespaces

6min
|
HCP
Vault

When Vault is primarily used as a central location to manage secrets, different teams may need to manage their secrets in a self-serving manner. HashiCups can implement a Vault-as-a-Service model, allowing each business unit or team (tenant) to manage their own secrets and policies. Most importantly, tenants work within their own Vault scope, isolated from other tenants. vault-namespace-multi-tenant

HCP Vault Dedicated uses the namespace feature. A namespace allows you to create separate groups of secrets, and apply policies to those namespaces to ensure each tenant can only access the secrets they have permission to. When you create a new HCP Vault Dedicated cluster, a Vault cluster with a default namespace of admin is provisioned.

In this tutorial, Oliver explores the creation of namespaces and learn how to navigate between them.

Prerequisites

Completed the Create a Vault Cluster on HashiCorp Cloud Platform (HCP) tutorial.
Completed the Access your HCP Vault Dedicated cluster tutorial.

Characteristics of Vault namespaces

A Vault namespace enables teams, organizations, or applications a dedicated, isolated environment. Each namespace has its own:

Policies
Auth methods
Secrets engines
Tokens
Identity entities and groups

Note

Vault creates tokens in a namespace or child-namespaces. Identity groups can pull in entities and groups from other namespaces.

Create namespaces

(Persona: operations)

You can create nested namespaces within another namespace in a hierarchical relationship.

In the Vault UI, select Access from the menu.
Select Namespaces and then click the Create namespace action.
Enter education in the Path field.
Click Save.
The education namespace is now a namespace under the admin namespace. You can see this relationship represented in the path admin/education/.
Click the admin namespace from the menu.
The namespace selector displays the namespaces of the current namespace.
Select the education namespace.
The current namespace changes to the admin/education/.
Navigate to Access > Namespaces and click the Create namespace action.
Enter training in the Path field.
Click Save.
The training namespace is now a namespace under the admin/education namespace. You can see this relationship represented in the path admin/education/training.
Use the namespace selector to navigate to the training namespace and then to the admin namespace.

If you did not set the VAULT_ADDR, VAULT_NAMESPACE, and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

In a terminal, verify you have set the required environment variables.
```
$ printenv | grep VAULT_

VAULT_ADDR=https://vault-cluster-public-vault-s3asm3str33t.78c57376.z1.hashicorp.cloud:8200
VAULT_NAMESPACE=admin
VAULT_TOKEN=hvs.CAESIOIdClADhaGU4YBVQ...snip...pQMEMuWGw3T0sQiZ4R
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.
Create a namespace called education.
```
$ vault namespace create education
Key     Value
---     -----
id      FgOVY
path    admin/education/
```
The education namespace is now a namespace under the admin namespace. You can see this relationship represented in the path admin/education/.
List all the namespaces.
```
$ vault namespace list

Keys
----
education/
```
The results display the education/ namespace. You can see the partial path displayed because you set the environment variable VAULT_NAMESPACE to admin/. With this environment variable set, the Vault CLI runs all commands in the context of the admin namespace.
Create a namespace called training as a namespace under admin/education/.
```
$ vault namespace create -namespace=admin/education training
Key     Value
---     -----
id      47O0M
path    admin/education/training/
```
The training namespace is now a namespace under the admin/education namespace. You can see this relationship represented in the path admin/education/training.
List the namespaces in the admin/education/ namespace.
```
$ vault namespace list -namespace=admin/education

Keys
----
training/
```
The results display the training/ namespace. The partial path is displayed because you passed the admin/education namespace to the command with the namespace parameter.
You can use the VAULT_NAMESPACE environment variable or -namespace flag to target a specific namespace. The -namespace or -ns flag overwrites the value set by the VAULT_NAMESPACE environment variable.

Each API request requires the token and Vault address. 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 namespace called education that is a child-namespace of the admin namespace.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin" \
    --request POST \
    $VAULT_ADDR/v1/sys/namespaces/education | jq -r ".data"
```
The request provides the admin namespace in the X-Vault-Namespace header. The education namespace is a namespace under the admin namespace. This relationship is represented as the path admin/education/.
Example output:
```
{
  "id": "yZWDA",
  "path": "admin/education/"
}
```
Create a namespace called training as a namespace under admin/education/.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    $VAULT_ADDR/v1/admin/education/sys/namespaces/training  | jq -r ".data"
```
The request provides the admin/education/ namespace through the API endpoint. The training namespace is a namespace under the admin/education education namespace. This relationship is represented as the path admin/education/training/.
Example output:
```
{
  "id": "iGp3G",
  "path": "admin/education/training/"
}
```

List the namespaces in the admin/ namespace.

Note

This example uses jq to process the JSON output for readability.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request LIST \
    $VAULT_ADDR/v1/admin/sys/namespaces | jq -r ".data"

Example output:

{
  "key_info": {
    "education/": {
      "id": "QdPD5",
      "path": "admin/education/"
    }
  },
  "keys": ["education/"]
}

List the namespaces in the admin/education/ namespace.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin/education" \
    --request LIST \
    $VAULT_ADDR/v1/sys/namespaces | jq -r ".data"

Example output:

{
  "key_info": {
    "training/": {
      "id": "Dbi4X",
      "path": "admin/education/training/"
    }
  },
  "keys": ["training/"]
}

You can specify the target namespace using the X-Vault-Namespace header in your HTTP request. Alternatively, you can add the namespace to the API endpoint. For example, /admin/sys/namespaces invokes the /sys/namespaces endpoint under the admin namespace.

Summary

In this tutorial you created new namespaces. You can use namespaces to isolate access to resources. To gain a greater understanding of namespaces complete the Manage tenants with Vault namespaces tutorial.

Next steps

In the next tutorial, you will enable a secrets engine and store a static secret.

Access a cluster

Create and store secrets