Multi-tenancy with Namespaces

6min
HCP
Vault

When Vault is primarily used as a central location to manage secrets, multiple organizations within a company may need to be able to manage their secrets in a self-serving manner. This means that a company needs to implement a Vault as a Service model allowing each organization (tenant) to manage their own secrets and policies. Most importantly, tenants should be restricted to work only within their tenant scope. vault-namespace-multi-tenant

To achieve this, HashiCorp Cloud Platform (HCP) Vault utilizes the concept of a namespace. 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 cluster, a Vault Enterprise cluster with a default namespace of admin is provisioned.

In this tutorial, you will explore the creation of namespaces and learn how to navigate between them.

NOTE: This step assumes that you created and connected to the HCP Vault cluster in the Create a Vault Cluster on HashiCorp Cloud Platform (HCP) step.

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

Tokens are locked to a namespace or child-namespaces. Identity groups can pull in entities and groups from other namespaces.

Create namespaces

You may define nested namespaces within a parent namespace. These child-namespaces enable further isolated environments under the parent namespace.

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 created as a child-namespace of the admin namespace. This relationship is represented as the path admin/education/.
Click the admin namespace from the menu.
The namespace selector displays the child-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 created as a child-namespace of the admin/education/ namespace. This relationship is represented as 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 and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

In a terminal, set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this enironment variable.
Create a namespace called education.
```
$ vault namespace create education
Key     Value
---     -----
id      FgOVY
path    admin/education/
```
The education namespace is created as a child-namespace of the admin namespace. This relationship is represented as the path admin/education/.
List all the namespaces.
```
$ vault namespace list

Keys
----
education/
```
The results display the education/ namespace. The partial path is displayed because the admin/ namespace was provided to the command by the environment variable.
Create a namespace called training as a child-namespace of admin/education/.
```
$ vault namespace create -namespace=admin/education training
Key     Value
---     -----
id      47O0M
path    admin/education/training/
```
The training namespace is created as a child-namespace of the admin/education/ namespace. This relationship is represented as 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 the admin/education namespace was provided to the command with the namespace parameter.

Summary

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 created as a child-namespace of 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 child-namespace of 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 created as a child-namespace of 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/"]
}

Summary

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.

Next steps

You created and navigated through Vault Enterprise namespaces. To gain a greater understanding of namespaces complete the Secure Multi-Tenancy with Namespaces tutorial.

Now you understand the fundamentals of Vault Enterprise namespaces. Learn how to store secrets using key/value secrets engine next.