It's better when it's simple

User Tools

Site Tools


pureldap Plugin

Compatible with DokuWiki

  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" unknown
  • 2018-04-22 "Greebo" unknown

plugin A new LDAP/AD auth plugin for DokuWiki

Last updated on

Similar to authad

Tagged with !experimental, activedirectory, ad, ldap, sso

This plugin implements authentication via ActiveDirectory (and possibly other LDAP servers later). It does not require any LDAP support in PHP and aims to have much better performance than the bundled authad plugin. This is especially true for all operations that do bulk user data requests. LDAP protocol connectivity is provided by the FreeDSx LDAP library.

This plugin is beta software. Be sure to read the whole of this page before installing it.

Background: Limitations of the bundled Plugins

DokuWiki includes two plugins that can authenticate users via the LDAP protocol: authldap and authad. Despite both plugins doing similar things, both are completely separate and share no code.

While authldap uses the PHP LDAP extension directly, authad makes use of the adLDAP library. There are multiple versions of this library - all slightly incompatible with each other. The authad Plugin uses version 1. The library abstracts away all the LDAP specifics, implements weird Microsoft quirks and makes it easier to configure AD access than doing it manually. However, it also limits the ability to customize the access to unusual AD setups.

Both plugins basically provide the same base features: authenticate users against an LDAP server and make the groups available for ACL management.

Both plugins share a few shortcomings when it comes to performance. This is especially notable when user data of many users needs to be queried.

  1. All user data has to be queried individually. Whenever a plugin requires the members of a given group, an additional query has to be made to fetch the user data for each individual member.
  2. Already queried user data isn't cached. So if a user's info is used several times, several LDAP queries have to be executed.
  3. The performance of the PHP LDAP extension itself isn't stellar either.

There are also quality problems in both plugins

  1. the adLDAP library is no longer maintained
  2. both plugins differ in functionality
  3. there is some code duplication between the plugins
  4. no automated tests

PureLDAP Feature Comparison

The pureLDAP plugin tries to remedy the issues above. Ultimately, the following goals should be met:

  1. single code base for LDAP and AD connections
  2. strong caching for queried data
  3. implement bulk queries
  4. implement the full feature set of both old plugins

Implementing all those features does not have to be done right away. It makes sense to first focus on one aspect (like AD connectivity) and implement features step by step.

The table below shows the current state. The plugin implements all the basic functionality to authenticate with typical Active Directory Setups and has proven to be reliant and performant in real life setups.

authldap authad pureldap
PHP LDAP extension required yes yes no
Server Support any AD only AD only, LDAP planned
Single Sign On no Kerberos/NTLM Kerberos/NTLM
SSL/TLS Cert Trust Settings via OS only via OS only Plugin Setting
Change Password no with Admin User only Admin User & Self-Service
Warn on expiring password no yes yes
Multi-Domain Support no yes no
Fetch additional attributes yes yes yes
Custom Attribute-Mapping yes no no
Full control on all LDAP queries yes no no
Automated Testing no no yes
Group Caching and Bulk Queries no no yes


Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Configuration and Migrating from authAD

Config parameters are somewhat different from the previous authad plugin. The config manager should help you out there. The authad documentation will still help you with setting up SSO etc.

Here's a typical example configuration:

$conf['plugin']['pureldap']['base_dn'] = 'DC=example,DC=local';
$conf['plugin']['pureldap']['suffix'] = 'example.local';
# DO NOT INCLUDE @ in the suffix, as it will be automatically added
$conf['plugin']['pureldap']['servers'] = array('dc.example.local');
$conf['plugin']['pureldap']['encryption'] = 'tls';
$conf['plugin']['pureldap']['validate'] = 'self';
$conf['plugin']['pureldap']['admin_username'] = 'adminuser';
$conf['plugin']['pureldap']['admin_password'] = 'adminpass';
$conf['plugin']['pureldap']['attributes'] = array('department','office');
$conf['plugin']['pureldap']['primarygroup'] = 'Domain Users';
$conf['plugin']['pureldap']['port'] = '636'; # port information only required if deviating from normal ports (389|636)
$conf['plugin']['pureldap']['recursivegroups'] = 1;
$conf['plugin']['pureldap']['sso'] = 1; # requires webserver setup

User and group names are cleaned less aggressively than in the old plugins. Previously names where mangled to fit DokuWiki page ID requirements, stripping spaces and other special chars. This was a one-way transformation which made it difficult to do reverse lookups (like searching for group members). The pureLDAP plugin will only lowercase user and group names, but keeps them as is otherwise. Existing ACLs may need adjustments accordingly.

If manually editing group name mappings in acl.auth.php make sure that authAd space format is convertoed to actual spaces using proper formating.

Example acl.auth.php - Groupname mapping of Domain Users:

  • AuthAD ACL formatting translates spaces to %5f (underscore _)
WikiDomainUsers: @Domain%5fUsers 16
  • PureLDAP ACL formatting translates spaces to %20
WikiDomainUsers: @Domain%20Users 16

Password Changes are supported when encryption is used. When a user changes their own password via the user profile, this change will be executed as the user themselves and the Active Directory will apply the appropriate Password Policies.

Password resets (where the user forgot their password) will always be executed with the configured administrative user which needs the appropriate permissions to change passwords for arbitrary users. These changes will ignore the password policy. It is recommended to enforce the policy on DokuWiki side using the passpolicy plugin. If you don't want this feature at all, you can disable password resets in the disableactions option.

Next Steps for Development

The Github Project: Full Feature Set provides a rough overview on the next steps that are needed to make the plugin an adequate replacement for the two old plugins. Most importantly, supporting non AD-Setups is currently completely missing.

More work is clearly needed. However, as a private person I have absolutely no use for LDAP or AD connectivity. Setting up test servers etc. and trying to replicate complex corporate setups is nearly impossible. TBH. there is really nothing here that motivates me to implement this except that it would be nice to have and is an interesting challenge - but so are many other things ;-).

So instead of me implementing this in my spare time, it makes more sense for CosmoCode to implement this. Or to rephrase it: it makes more sense for me to create this while being paid to do so. Doing it at my dayjob also provides me with the support of my colleagues when it comes to coding, research and sysadmin tasks.

In short: If you want to make use of more performant LDAP or AD connectivity in DokuWiki and have the company resources to fund that, please get in contact at dokuwiki [at] cosmocode [dot] de.

plugin/pureldap.txt · Last modified: 2023-12-05 23:50 by andi

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki