LDAP Authentication Plugin

Introduction

This plugin enables centralized authentication using LDAP. Instead of managing passwords locally in Typemill, users can log in using their existing directory credentials. This is useful for centralized user management in organizations.

The core features are:

• Connect once with a service account
• Search users dynamically
• Authenticate securely via LDAP bind
• Optionally create local users automatically

The plugin is designed to work with both OpenLDAP and Active Directory setups.

Typical Scenario

A common setup looks like this:

• Your organization manages users in an LDAP directory
• Users are stored under a specific branch, for example: ou=users,dc=example,dc=com
• Each user has a unique identifier such as: uid=testuser
• Typemill connects to LDAP using a service account (Bind DN)

During login:

• Typemill binds to LDAP with the service account
• Searches for the user using a filter (e.g. (uid=testuser))
• Attempts to bind as the user with the provided password
• If successful → login is granted

Requirements

• A working LDAP server (e.g. OpenLDAP or Active Directory)
• PHP LDAP extension enabled (php-ldap)
• Users must exist in LDAP and be searchable

Plugin Settings

• Disable local login (ldap_only): Force all users to authenticate via LDAP. Local Typemill passwords will be ignored.
• Automatically create users (auto_create):
  • If enabled, Typemill will create a local user account after the first successful LDAP login.
  • If disabled: You must create users manually in Typemill. The username must match the LDAP username
• Default role (default_role): Role assigned to newly created users (e.g. member, editor, admin).
• LDAP Host (host): The address of your LDAP server (ldap://127.0.0.1 or ldaps://ldap.example.com)
• LDAP Port (port): Common values are 389 (standard LDAP) and 636 (secure LDAPS)
• Bind DN (bind_dn): The service account used to connect and search users. Example: cn=admin,dc=example,dc=com
• Bind Password (bind_password): Password for the service account.
• Base DN (base_dn): The directory path where users are stored. Example: ou=users,dc=example,dc=com Only users within this subtree can authenticate.
• User Filter (user_filter): LDAP filter used to find users. Example: (uid={username}). {username} will be replaced with the login input. Example for Active Directory: (sAMAccountName={username})
• Username Attribute (username_attribute): LDAP attribute used as username. Examples: uid (OpenLDAP) or sAMAccountName (Active Directory)
• Email Attribute (email_attribute): LDAP attribute that contains the user email. Default: mail
• Use StartTLS (starttls): Enable encryption when using ldap://. Required if your server supports StartTLS. Not needed when using ldaps://

Example Configuration

OpenLDAP

Host: ldap://127.0.0.1
Port: 389
Bind DN: cn=admin,dc=example,dc=com
Bind Password: ********
Base DN: ou=users,dc=example,dc=com
User Filter: (uid={username})
Username Attribute: uid
Email Attribute: mail
StartTLS: false

Active Directory

Host: ldap://ad.example.com
Port: 389
Bind DN: cn=ldap-reader,dc=example,dc=com
Bind Password: ********
Base DN: dc=example,dc=com
User Filter: (sAMAccountName={username})
Username Attribute: sAMAccountName
Email Attribute: mail
StartTLS: true

Limitations

• No automatic UID/GID management
  The plugin does not manage POSIX attributes like uidNumber or gidNumber.
• No group-to-role mapping (yet)
  Roles are assigned statically via default_role.
• No nested LDAP queries
  Only a single user search is performed.
• No fallback (if disabled)
  If ldap_only is enabled and LDAP is unavailable, users cannot log in.
• Requires correct Base DN
  If base_dn is wrong, users will not be found even if they exist.

Troubleshooting

User not found

• Check base_dn
• Verify user_filter
• Test with:

ldapsearch -x -b "ou=users,dc=example,dc=com" "(uid=testuser)"

Login fails

• Verify user password by testing:

ldapwhoami -x -D "uid=testuser,ou=users,dc=example,dc=com"

Connection issues

• Check host and port
• Verify TLS/SSL configuration
• Ensure PHP LDAP extension is installed