Effortless Role Management: Using LDIF Files with HCP Vault Dedicated LDAP Secret Engine – HashiCorp Help Center

Objective

This guide provides detailed instructions on how to create roles that map a name in Vault to an entry in OpenLDAP. Using LDIF files which can be used to represent complex directory structures and relationships, supporting a wide range of attributes and object classes.

LDIF (LDAP Data Interchange Format) is a standard plain-text format used to represent directory entries and updates in LDAP (Lightweight Directory Access Protocol) directories. User account management is provided through LDIF entries. It supports a variety of LDAP operations, including add, delete, modify, and modify DN (distinguished name).

Advantages of using LDIF files

Using LDIF files for configuring roles in the LDAP secrets engine in Vault offers significant advantages in terms of consistency, simplicity, efficiency, and error reduction.

They also serve as reusable templates for common LDAP operations, reducing the risk of errors and ensuring consistent application of settings.

Automating the application of LDIF files reduces the risk of manual errors that can occur when writing and applying configurations directly.

Prerequisites

HashiCorp Vault Dedicated Cluster deployed and running
Access to an LDAP directory with appropriate permissions

Steps

1. Login to your HCP Vault Dedicated Cluster, Enable and Configure LDAP Secret Engine.

Kindly refer to https://developer.hashicorp.com/vault/tutorials/secrets-management/openldap#start-vault for detailed instruction on "How to login to HCP Vault Dedicated Cluster", "Enable LDAP Secret Engine", and "Configure LDAP Secret Engine"

2. Create a Role in HCP Vault Dedicated through LDIF files

Create a role that defines the scope and permissions of the generated credentials. LDIF files for creating roles are preferred over writing roles directly in the command as LDIF files are well-suited for batch processing, allowing administrators to create, modify, or delete multiple directory entries in a single operation. This can be achieved using below command :

vault write ldap/roles/dynamic-role \
    creation_ldif=@creation.ldif \
    deletion_ldif=@deletion.ldif \
    default_ttl=1h \
    max_ttl=24h

creation_ldif: Path to an LDIF file with the LDAP entry creation instructions.
deletion_ldif: Path to an LDIF file with the LDAP entry deletion instructions.
default_ttl: The default time-to-live for the generated credentials.
max_ttl: The maximum time-to-live for the generated credentials.

Example LDIF Files

creation.ldif:

dn: CN={{.Username}},ou=people,dc=example,dc=com
objectClass: top
objectClass: person
sn: User
userPassword: {{password}}

deletion.ldif:

dn: CN={{.Username}},ou=people,dc=example,dc=com
changetype: delete

modification.ldif

If you are making several modifications to an entry, then, between each modification you enter, add a line that contains a hyphen (-) only. For example:

dn: CN={{.Username}},ou=people,dc=example,dc=com
changetype: modify
add: work-phone
work-phone: XXXX-XXXX-XXXX
work-phone: XXXX-XXXX-XXXX
-
delete: home-fax
-
replace: home-phone
home-phone: XXXX-XXXX-XXXX

sample ldif for multiple operations

dn: CN={{.Username}},OU=HashiVaultDedicated,DC=adtesting,DC=lab
changetype: add
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
userPrincipalName: {{.Username}}@adtesting.lab
sAMAccountName: {{.Username}}

dn: CN={{.Username}},OU=HashiVaultDedicated,DC=adtesting,DC=lab
changetype: modify
replace: unicodePwd
unicodePwd::{{ printf "%q" .Password | utf16le | base64 }}
-
replace: userAccountControl
userAccountControl: 66048
-

dn: CN=test-group,OU=HashiVaultDedicated,DC=adtesting,DC=lab
changetype: modify
add: member
member: CN={{.Username}},OU=HashiVaultDedicated,DC=adtesting,DC=lab
-

If you were to configure this directly in HCP Vault Dedicated without using LDIF files, the configuration might become cumbersome and error-prone, especially for complex or bulk operations. Instead, with LDIF files:

Create Once, Use Many: Define the creation and deletion logic once in the LDIF files and reuse them across multiple roles and configurations.
Cleaner Configuration: The Vault commands remain clean and focused on referencing the LDIF files rather than embedding all the LDAP logic directly.

Points to Remember when crafting LDIF entries

There should not be any trailing spaces on any line, including empty lines.
Each modify block needs to be preceded with an empty line.
Multiple modifications for a dn can be defined in a single modify block. Each modification needs to close with a single dash (-).

A good reference for proper LDIF syntax can be found here.

Common error encountered during role creation through LDIF files

invalid creation.ldif : LDIF is invalid : Error in line 2 : missing 'dn:'

Solution

Please ensure to add an @ sign before the ldif file name while creating the role as per :

$ vault write ldap/role/dynamic-role \
creation_ldif=@/path/to/creation.ldif \
deletion_ldif=@/path/to/deletion.ldif \
rollback_ldif=@/path/to/rollback.ldif \
default_ttl=1h \
max_ttl=24h