Introduction
In multi-tenant Vault environments, managing authentication and access policies across namespaces can quickly become complex. HashiCorp Vault Enterprise supports identity groups and namespaces, which when paired with an external identity provider such as LDAP enables secure, centralized access management.
This guide walks through configuring Vault to authenticate users from an OpenLDAP directory, associate external LDAP groups with Vault identity groups, and apply namespace-specific policies through group aliasing and internal group mapping.
LDAP groups structure and configuration
The LDAP group structure includes one group and one user.
The "dev" group is designated as a testing group for developers and includes one member, Laura.
|
dn: ou=groups,dc=example,dc=org dn: ou=users,dc=example,dc=org dn: cn=dev,ou=groups,dc=example,dc=org dn: cn=laura,ou=users,dc=example,dc=org |
Run an OpenLDAP server locally using Docker:
| docker run --name my-openldap-container \ --hostname ldap.my-company.com \ -p 389:389 \ --detach osixia/openldap:1.2.1 |
Check that the container is running:
| docker ps | grep ldap |
Import the LDIF into the LDAP server:
| ldapadd -x -W -D "cn=admin,dc=example,dc=org" -f your-ldif-file.ldif |
Vault LDAP Auth Configuration
Enable Vault LDAP auth method and configure the connection in the Root Namespace
| vault auth enable ldap vault write auth/ldap/config \ url="ldap://localhost" \ userdn="ou=users,dc=example,dc=org" \ groupdn="ou=groups,dc=example,dc=org" \ groupfilter="(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))" \ groupattr="cn" \ starttls=false \ binddn="cn=admin,dc=example,dc=org" \ bindpass="admin" |
Before proceeding, create a Vault policy that aligns with your access requirements. This policy will be necessary in the next step when associating it with an external group. For guidance on writing policies, refer to the Vault Policies documentation.
Alternatively, if you choose not to attach any policy when creating the external group, users will be granted only the default policy in the root namespace upon login.
Create External Identity Group
| vault write identity/group name=dev type=external policies=admin Key Value --- ----- id a7145e4f-c9e2-188d-7397-ba22292e030b name dev |
Save the group ID (e.g., a7145e4f-c9e2-188d-7397-ba22292e030b)
Retrieve the LDAP mount accessor and make a note of its accessor ID.
| vault auth list Path Type Accessor Description Version ---- ---- -------- ----------- ------- ldap/ ldap auth_ldap_c7bde2fe n/a n/a |
Create Group Alias
making sure your alias is named "dev" (to match the LDAP group name).
| vault write identity/group-alias name=dev mount_accessor=auth_ldap_c7bde2fe canonical_id=a7145e4f-c9e2-188d-7397-ba22292e030b Key Value --- ----- canonical_id a7145e4f-c9e2-188d-7397-ba22292e030b id b9c80b6b-82be-dbb9-3c4a-78372787186a |
Create Namespace and Internal Group Mapping
Create a Namespace
| vault namespace create test |
Create Internal Group in Namespace
Before that, define the training-admin policy in the test namespace.Attach the training-admin policy to this internal group. For guidance on writing policies, refer to the write policies step.
| vault write -namespace=test identity/group \ name="Training Admin" \ policies="training-admin" \ member_group_ids=a7145e4f-c9e2-188d-7397-ba22292e030b |
This internal group links the external dev group (from root namespace) to the training-admin policy inside test.
Vault Login Using LDAP
Login as LDAP User (e.g., laura) in Root Namespace
|
vault login -method=ldap username=laura Key Value |
| vault token lookup Key Value --- ----- accessor xxxxx creation_time 1754603949 creation_ttl 768h display_name ldap-laura entity_id 349c4173-61aa-b16d-8deb-0c42cf91712b expire_time 2025-09-08T16:59:09.771385-05:00 explicit_max_ttl 0s external_namespace_policies map[KDnEQ:[training-admin]] id hvs.xxxxxxx identity_policies [admin] issue_time 2025-08-07T16:59:09.771391-05:00 meta map[username:laura] num_uses 0 orphan true path auth/ldap/login/laura policies [default] renewable true ttl 767h59m47s type service |
Upon successful login, the Vault token will have
- identity_policies: ["admin"]
- external_namespace_policies: {"test": ["training-admin"]}
Switch to Target Namespace
Once authenticated in the root namespace, users like laura can operate in other namespaces via their mapped policies.
|
export VAULT_NAMESPACE=test
|
The user will now have access to secrets and operations allowed by the training-admin policy in the test namespace.
Summary
In this setup, LDAP authentication is centralized by enabling the auth method once in the root namespace, simplifying configuration and maintenance. External LDAP groups—such as dev are mapped to Vault identity groups, allowing for consistent identity management. These identity groups are then linked to internal groups within individual namespaces, enabling namespace-specific policy enforcement. As a result, users authenticate a single time in the root namespace and seamlessly inherit the appropriate permissions across multiple namespaces through group-based policy mappings.