Create Users in OpenLDAP

Create OpenLDAP users with valid DNs, object classes, required attributes, password hashes, LDIF files, and appropriately scoped permissions.

Type
Tutorial
Level
Intermediate
Technologies
OpenLDAP, LDAP
On this page

Adding users to OpenLDAP is a precise, schema-driven process. Whether administering an existing directory or building authentication flows in code, user creation hinges on correctly formatting data, understanding schema requirements, and using appropriate administrative tools. This guide explains, step by step, how to create user entries in OpenLDAP, construct compliant LDIF files, securely handle passwords, and avoid common directory provisioning mistakes.

Understanding User Entries in OpenLDAP

An LDAP user entry is a record in the directory that represents a person or account capable of authentication and association with group membership. Each user is stored as a distinct entry in the LDAP Data Information Tree (DIT). The DIT is a hierarchical structure; user records are typically placed beneath a designated organizational unit (OU), most often named People or similar, and the entry is identified by a distinguished name (DN).

Example DN:

text
uid=alice,ou=People,dc=example,dc=com

Here, uid=alice is the user's unique identifier, and ou=People,dc=example,dc=com specifies where in the hierarchy the entry resides.

User Entry Schema: ObjectClasses and Required Attributes

Each LDAP entry—including users—must comply with schema rules enforced by the directory. These rules are defined by objectClass values, which collectively determine:

  • Which attributes are permitted (MAY)
  • Which attributes are mandatory (MUST)
  • The structure and semantics of an entry

For user accounts, two objectClasses are most common:

  • inetOrgPerson: A general-purpose user schema, often used for human users and rich identity attributes.
  • posixAccount: Required for compatibility with UNIX/POSIX systems (home directories, UID/GID).

Minimum Required Attributes

For a user entry to be accepted by OpenLDAP, all required attributes of its objectClasses must be present. Some of the most critical attributes (combining inetOrgPerson and posixAccount) are:

  • objectClass (must appear multiple times, once per class)
  • uid (username, unique within the OU)
  • cn (common name, typically full name)
  • sn (surname)
  • uidNumber (unique integer user ID; POSIX)
  • gidNumber (primary group ID; POSIX)
  • homeDirectory (POSIX home directory path)
  • userPassword (see secure handling below)

Additional attributes (e.g., mail, loginShell) may be used if needed, but are not always required.

Building an LDIF File for a New User

LDAP Data Interchange Format (LDIF) is the standard text format for expressing directory entries and operations. To create a user, construct an LDIF file that expresses the exact content of the user entry per the required attributes and DIT placement.

Minimal example of a user LDIF:

ldif
dn: uid=alice,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
uid: alice
sn: Alice
cn: Alice Smith
uidNumber: 1001
gidNumber: 1000
homeDirectory: /home/alice
userPassword: {SSHA}k9hr...<hash>

Key points:

  • The dn: line defines the full distinguished name of the user entry.
  • Each objectClass must be explicitly listed.
  • All required attributes as determined by the objectClasses must be included.
  • Do not include attributes not allowed by the declared objectClasses; schema violations produce errors.

Setting Passwords: Best Practices with userPassword and slappasswd

OpenLDAP stores user passwords in the userPassword attribute. For strong security and to comply with best practices:

  • Never store plaintext passwords in LDIF files.
  • Use the slappasswd utility to create a salted, hashed password value (commonly SSHA).

Example workflow:

  1. Run slappasswd on the command line; enter the desired password when prompted.
  2. Copy the resulting hash (e.g., {SSHA}FDqw2...) into the userPassword: field in your LDIF.

Supported password hash schemes include SSHA, SHA, and others. SSHA is widely recommended for its salted, one-way hashing.

Sample snippet in LDIF:

ldif
userPassword: {SSHA}FDqw2dQ7fgyYb896ViLf9I6rqkKAM4vJ

Adding the User: Using ldapadd and Required Permissions

With your LDIF file prepared, add the user to OpenLDAP using the ldapadd command-line tool. This tool performs an LDAP Add operation and requires authentication with sufficient privileges (usually the root DN or designated admin).

Command structure:

bash
ldapadd -D "cn=admin,dc=example,dc=com" -W -f newuser.ldif
  • -D is the bind DN (typically your directory admin).
  • -W prompts for the admin password.
  • -f specifies the LDIF file to import.

Important: Only users with write access to the relevant part of the DIT (usually the root DN or accounts with delegated privileges) can add user entries. Attempting to add entries with insufficient permission leads to authorization errors.

Alternative Methods: GUI Tools and Scripting

While most routines use the command-line, GUI LDAP browsers like JXplorer provide an alternative interface for browsing, adding, or editing entries. These tools wrap the same underlying LDAP operations:

  • Filling in forms for attributes and classes
  • Issuing LDAP Add requests to the server

There is no fundamental difference—in both cases, a properly formed entry is submitted via the LDAP protocol. GUI tools can aid visibility and reduce some manual mistakes but do not bypass schema enforcement or security.

Scripting and automation (e.g., Bash scripts calling ldapadd, or tools like ldapscripts) can further streamline user provisioning, especially for bulk operations. Scripts essentially automate the LDIF generation and add steps, obeying the same directory logic and permissions.

Organizing Users and Groups: OUs and Group Membership

Structure your DIT for maintainability and scalability. Common approaches:

  • Users are located under an OU such as ou=People,dc=example,dc=com.
  • Groups are placed in a separate OU, e.g., ou=Groups,dc=example,dc=com.

Group entries use their own objectClasses (e.g., posixGroup) and reference members by their uid or distinguished name (via the member or memberUid attribute).

Example DIT fragment:

ldif
dn: ou=People,dc=example,dc=com
dn: ou=Groups,dc=example,dc=com
dn: cn=developers,ou=Groups,dc=example,dc=com
objectClass: posixGroup
cn: developers
gidNumber: 1000
memberUid: alice

This structure ensures that users and groups can be easily managed, mapped, and provisioned.

Common Mistakes and Troubleshooting

Some frequent pitfalls when adding users to OpenLDAP:

  • Schema violations: Missing required attributes or including disallowed attributes will trigger errors during ldapadd. Always verify the set of objectClasses and their requirements.
  • Permission errors: Attempting to add users without proper admin credentials leads to "insufficient access" errors.
  • Direct database editing: Never edit OpenLDAP database files directly; always use supported tools like ldapadd or ldapmodify (or slapadd for offline, initial loading).
  • Unhashed passwords: Storing plaintext passwords exposes credentials during import and at rest; always hash with slappasswd.

Diagnosing errors generally involves reading the detailed output of ldapadd or checking the server logs for schema and ACL failures.

OpenLDAP vs Active Directory User Creation

Although both OpenLDAP and Active Directory are LDAP-compatible, there are differences in user creation:

  • ObjectClasses: OpenLDAP typically uses inetOrgPerson and/or posixAccount, while Active Directory relies on its own schema (such as user).
  • Attribute names: Some attribute names and requirements differ. For instance, OpenLDAP requires uid, while Active Directory focuses on sAMAccountName and others.
  • Group membership: The method and attribute used for group membership and unique identifiers (“distinguishedName” vs “uid”) may not fully align; direct LDIF migrations require mapping.

When migrating or integrating, always carefully review schemas and adjust LDIFs or provisioning logic accordingly.

Bulk User Addition and Script Automation

Bulk provisioning is achieved by concatenating multiple user entries in a single LDIF file and processing them via ldapadd (if the directory is online) or slapadd (if offline, commonly on initial population).

Caveats:

  • Each entry in the LDIF must be fully schema-compliant.
  • Errors in any record can halt the import or create partial states.
  • Scripting can improve efficiency but should still validate data against the schema.

Summary and Further Reading

Successfully creating users in OpenLDAP requires careful conformance to schema, secure password practices, and appropriate use of administrative tooling. By structuring LDIF files accurately and understanding DIT organization, you can reliably provision and manage user accounts—whether manually, via GUI, or with automation.

For advanced scenarios, including schema extensions, group hierarchies, and integration with external authentication, consult the authoritative documentation below.

Sources:

  • OpenLDAP Software 2.6 Administrator's Guide
  • OpenLDAP 2.3 Quick-Start Guide
  • OpenLDAP 2.2 Database Tools
  • RFC 4512: LDAP Directory Information Models

Sources

Related resources