Vault Enterprise namespaces

Many organizations implement Vault as a "service", providing centralized management for teams within an organization while ensuring that those teams operate within isolated environments known as tenants.

There are two common challenges when implementing this architecture in Vault:

Tenant isolation
Frequently teams within a VaaS environment require strong isolation from other users in their policies, secrets, and identities. Tenant isolation is typically a result of compliance regulations such as GDPR, though it may be necessitated by corporate or organizational infosec requirements.
Self-management
As new tenants are added, there is an additional human cost in the management overhead for teams. Given that tenants will likely have different policies and request changes at a different rate, managing a multi-tenant environment can become very difficult for a single team as the number of tenants within that organization grow.
'Namespaces' is a set of features within Vault Enterprise that allows Vault environments to support Secure Multi-tenancy (or SMT) within a single Vault infrastructure. Through namespaces, Vault administrators can support tenant isolation for teams and individuals as well as empower delegated administrators to manage their own tenant environment.

Architecture

Namespaces are isolated environments that functionally exist as "Vaults within a Vault." They have separate login paths and support creating and managing data isolated to their namespace. This data includes the following:

Secret Engines
Auth Methods
ACL, EGP, and RGP Policies
Password Policies
Identities (Entities, Groups)
Tokens

Rather than rely on Vault system admins, namespaces can be managed by delegated admins who can be prescribed administration rights for their namespace. These delegated admins can also create their own child namespaces, thereby prescribing admin rights on a subordinate group of delegate admins.

Child namespaces can share policies from their parent namespaces. For example, a child namespace may refer to parent identities (entities and groups) when writing policies that function only within that child namespace. Similarly, a parent namespace can have policies asserted on child identities. This behavior can be configured using the group-policy-application API, and can be set to allow policies to be applied irrespective of namespace hierarchy, allowing sharing across any namespace.

Administrative namespaces

The Vault API includes system backend endpoints, which are mounted under the sys/ path. System endpoints let you interact with the internal features of your Vault instance. For security reasons, some of the system backend endpoints are restricted, and can only be called from the root namespace or using a token in the root namespace with elevated permissions. These endpoints are documented below.

By default, Vault allows non-root calls to the less sensitive system backend endpoints. However, there may be instances where a Vault operator needs to provide access to a subset of the restricted endpoints, like sys/audit-hash and sys/monitor, without granting access to the full set of privileged sys/ paths. An administrative namespace lets Vault operators grant access to a subset of privileged endpoints by setting a parameter in their Vault configuration file.

Usage

API operations performed under a namespace can be done by providing the relative request path along with the namespace path using the X-Vault-Namespace header. Similarly, the namespace header value can be provided in full or partially when reaching into nested namespaces. When provided partially, the remaining namespace path must be provided in the request path in order to reach into the desired nested namespace.

Alternatively, the fully qualified path can be provided without using the X-Vault-Namespace header. In either scenario, Vault will construct the fully qualified path from these two sources to correctly route the request to the appropriate namespace.

For example, these three requests are equivalent:

Path: ns1/ns2/secret/foo
Path: secret/foo, Header: X-Vault-Namespace: ns1/ns2/
Path: ns2/secret/foo, Header: X-Vault-Namespace: ns1/

Tip

See the Commands (CLI) - namespace page to learn more about the namespace command and subcommands to create and manage namespaces.

Namespace naming restrictions

Consider the following namespace name restrictions:

Cannot end with /
Cannot contain spaces
The root is the top-level namespace. You cannot create another namespace named "root" under the root namespace

In addition, the following paths are reserved by Vault so that they cannot be the namespace name.

Tip

Refer to the Namespace limits section of the Limits and Maximums documentation for the limits associated with the Vault's storage backend.

To learn more about the recommended approach to structure your namespaces, read the Vault Namespace and Mount Structuring Guide tutorial.

Root-only API paths

There are certain API paths that can only be called from the root namespace:

Tutorial

Refer to the following tutorials to learn more about Vault namespaces:

API

Vault Enterprise namespace has a full HTTP API. Please see the /sys/namespaces API for more details.