Namespaces

Many organizations implement OpenBao as a service to provide centralized management of sensitive data and ensure that the different teams in an organization operate within isolated environments known as tenants.

Multi-tenant environments have the following implementation challenges:

• Tenant isolation. Teams within a Visualization as a Service (VaaS) environment require strong isolation for their policies, secrets, and identities. Tenant isolation may also be required due to organizational security and privacy requirements or to address compliance regulations like GDPR.
• Long-term management. Tenants typically have different policies and teams request changes to their tenants at different rates. As a result, managing a multi-tenant environment can become difficult for a single team as the number of tenants within the organization grows.

Namespaces support secure multi-tenancy (SMT) within a single OpenBao instance with tenant isolation and administration delegation so OpenBao administrators can empower delegates to manage their own tenant environment.

When you create a namespace, you establish an isolated environment with separate login paths that functions as a mini-OpenBao instance within your OpenBao installation. Users can then create and manage their sensitive data within the confines of that namespace, including:

• secret engines
• authentication methods
• ACL, EGP, and RGP policies
• password policies
• entities
• identity groups
• tokens

Namespace naming restrictions

Valid OpenBao namespace names:

• CANNOT end with /
• CANNOT contain spaces
• CANNOT be one of the following reserved strings:
  • .
  • ..
  • root
  • sys
  • audit
  • auth
  • cubbyhole
  • identity

Refer to the Namespace limits section of OpenBao limits and maximums for storage limits related to managing namespaces.

Child namespaces

A child namespace is any namespace that exists entirely within the scope of another namespace. The containing namespace is the parent namespace. For example, given the namespace path A/B/C:

• A is the top-most namespace and exists under the root namespace for the OpenBao instance.
• B is a child namespace of A and the parent namespace of C.
• C is a child namespace of B and the grandchild namespace of A.

Children can inherit elements from their parent namespaces. For example, policies for a child namespace might reference entities or groups from the parent namespace. Parent namespaces can also assert policies on identities within a child namespace.

Delegation and administrative namespaces

OpenBao system administrators can assign administration rights to delegate admins to allow teams to self-manage their namespace. In addition to basic management, delegate admins can create child namespaces and assign admin rights to subordinate delegate admins.

Administrators of child namespaces cannot escape the limits of namespace, though may create additional nested namespaces of their own.

OpenBao API and namespaces

Users can perform API operations under a specific namespace by setting the X-Vault-Namespace header to the absolute or relative namespace path. Relative namespace paths are assumed to be child namespaces of the calling namespace. You can also provide an absolute namespace path without using the X-Vault-Namespace header.

OpenBao constructs the fully qualified namespace path based on the calling namespace and the X-Vault header to route the request to the appropriate namespace. For example, the following requests all route to the ns1/ns2/secret/foo namespace:

1. Path: ns1/ns2/secret/foo
2. Path: secret/foo, Header: X-Vault-Namespace: ns1/ns2/
3. Path: ns2/secret/foo, Header: X-Vault-Namespace: ns1/

info

Use the /sys/namespaces API or namespace CLI command to manage your namespaces.

Restricted API paths

The OpenBao API includes system backend endpoints, which are mounted under the sys/ path. System endpoints let you interact with the internal features of your OpenBao instance.

By default, OpenBao allows non-root calls to the less-sensitive system backend endpoints. But, for security reasons, OpenBao restricts access to some of the system backend endpoints to calls from the root namespace or calls that use a token in the root namespace with elevated permissions.

<a id="privileged-endpoints" />

::info

The CLI commands associated with restricted API paths are also restricted.

:::

API path	Root	Child
sys/audit	YES	NO
sys/audit-hash	YES	NO
sys/config/auditing	YES	NO
sys/config/cors	YES	NO
sys/config/reload	YES	NO
sys/config/state	YES	NO
sys/config/ui	YES	NO
sys/decode-token	YES	NO
sys/generate-recovery-token	YES	NO
sys/generate-root	YES	NO
sys/health	YES	NO
sys/host-info	YES	NO
sys/in-flight-req	YES	NO
sys/init	YES	NO
sys/internal/counters/activity	YES	NO
sys/internal/counters/activity/export	YES	NO
sys/internal/counters/activity/monthly	YES	NO
sys/internal/counters/config	YES	NO
sys/internal/inspect/router	YES	NO
sys/key-status	YES	NO
sys/loggers	YES	NO
sys/managed-keys	YES	NO
sys/metrics	YES	NO
sys/mfa/method	YES	NO
sys/monitor	YES	NO
sys/pprof	YES	NO
sys/quotas/config	YES	NO
sys/quotas/lease-count	YES	NO
sys/quotas/rate-limit	YES	NO
sys/raw	YES	NO
sys/rekey	YES	NO
sys/rekey-recovery-key	YES	NO
sys/replication/merkle-check	YES	NO
sys/replication/recover	YES	NO
sys/replication/reindex	YES	NO
sys/replication/status	YES	NO
sys/rotate	YES	NO
sys/rotate/config	YES	NO
sys/rotate/keyring	YES	NO
sys/rotate/keyring/config	YES	NO
sys/rotate/root	YES	NO
sys/seal	YES	NO
sys/sealwrap/rewrap	YES	NO
sys/step-down	YES	NO
sys/storage	YES	NO
sys/sync/config	YES	NO
sys/unseal	YES	NO