DokuWiki Authentication Plugins — LDAP, Active Directory, OAuth, and SAML

In this tutorial, you'll learn how to integrate DokuWiki with external authentication systems including LDAP directories, Active Directory, OAuth providers like Google and GitHub, SAML-based identity providers, and MySQL-based authentication.

What You'll Learn

• When to use external authentication vs built-in
• LDAP authentication configuration
• Active Directory integration
• OAuth authentication (Google, GitHub, etc.)
• SAML-based single sign-on
• MySQL authentication backend
• Authentication plugin troubleshooting

Why It Matters

The plain-text authentication file (users.auth.php) works for small teams, but it does not scale. With external authentication, users log in with their existing corporate credentials. No separate account creation, no password management, no duplicate user databases. For organizations with 50+ users, external authentication is essential.

Real-World Use

A company with 200 employees uses Active Directory for all IT systems. They configure DokuWiki to authenticate against AD. Employees log in with their existing Windows credentials. When a new employee joins, IT creates their AD account, and they automatically have access to DokuWiki. When someone leaves, IT disables their AD account, and their wiki access is revoked immediately. No manual account management needed.

Learning Path

flowchart LR
  A[Advanced ACL] --> B[Authentication]
  B --> C[Spam Protection]
  C --> D[Plugin System]
  D --> E[Essential Plugins]
  E --> F[Custom Plugins]

When to Use External Authentication

LDAP Authentication

LDAP (Lightweight Directory Access Protocol) is a standard protocol for accessing directory services. Many organizations use OpenLDAP or similar systems.

Configuration

<?php
// conf/local.php
$conf['authtype'] = 'ldap';

$conf['auth']['ldap']['server'] = 'ldap://ldap.example.com:389';
$conf['auth']['ldap']['usertree'] = 'ou=People,dc=example,dc=com';
$conf['auth']['ldap']['grouptree'] = 'ou=Group,dc=example,dc=com';
$conf['auth']['ldap']['userfilter'] = '(uid=%{user})';
$conf['auth']['ldap']['groupfilter'] = '(cn=%{group})';
$conf['auth']['ldap']['version'] = 3;
$conf['auth']['ldap']['starttls'] = 1;
$conf['auth']['ldap']['binddn'] = 'cn=admin,dc=example,dc=com';
$conf['auth']['ldap']['bindpw'] = 'admin-password';

Parameters Explained

• server: LDAP server URL (ldap:// or ldaps://)
• usertree: Base DN for user search
• grouptree: Base DN for group search
• userfilter: Filter to find a user by login name
• groupfilter: Filter to match groups
• version: LDAP protocol version (3 recommended)
• starttls: Enable TLS encryption
• binddn: Admin DN for initial bind (optional)
• bindpw: Password for initial bind

Testing LDAP Connection

# Test LDAP connection from command line
ldapsearch -x -H ldap://ldap.example.com -b "dc=example,dc=com" "(uid=jdoe)"

Active Directory Authentication

Active Directory is Microsoft's directory service. DokuWiki's LDAP plugin works with AD.

Configuration

<?php
// conf/local.php
$conf['authtype'] = 'ldap';

$conf['auth']['ldap']['server'] = 'ldap://dc01.example.com:389';
$conf['auth']['ldap']['usertree'] = 'dc=example,dc=com';
$conf['auth']['ldap']['grouptree'] = 'dc=example,dc=com';
$conf['auth']['ldap']['userfilter'] = '(sAMAccountName=%{user})';
$conf['auth']['ldap']['groupfilter'] = '(cn=%{group})';
$conf['auth']['ldap']['version'] = 3;
$conf['auth']['ldap']['starttls'] = 1;
$conf['auth']['ldap']['binddn'] = 'cn=binduser,cn=Users,dc=example,dc=com';
$conf['auth']['ldap']['bindpw'] = 'bind-password';
$conf['auth']['ldap']['mapping']['name'] = 'displayName';
$conf['auth']['ldap']['mapping']['email'] = 'mail';
$conf['auth']['ldap']['mapping']['grps'] = 'memberOf';

AD-Specific Settings

• userfilter: Use sAMAccountName for Windows login names
• mapping: Map AD attributes to DokuWiki fields (name, email, groups)

Group Mapping

AD groups are returned as distinguished names (e.g., CN=Wiki Editors,CN=Users,DC=example,DC=com). You may need to strip the DN to get the group name:

<?php
// conf/local.php
$conf['auth']['ldap']['mapping']['grps'] = 'memberOf';
$conf['auth']['ldap']['cvtgrps'] = 'stripBase'; // Strip base DN from group names

OAuth Authentication

OAuth allows users to log in with their Google, GitHub, or other OAuth provider accounts.

Installing the OAuth Plugin

cd /var/www/html/wiki/lib/plugins/
wget https://github.com/username/dokuwiki-plugin-oauth/archive/master.zip
unzip master.zip
mv dokuwiki-plugin-oauth-master oauth

Google OAuth Configuration

1. Create credentials in Google Cloud Console (OAuth 2.0 Web Application)
2. Set redirect URI to https://yourserver/wiki/lib/plugins/oauth/google.php
3. Configure the plugin in conf/local.php:

<?php
$conf['authtype'] = 'oauth';
$conf['auth']['oauth']['google']['client_id'] = 'your-client-id';
$conf['auth']['oauth']['google']['client_secret'] = 'your-client-secret';
$conf['auth']['oauth']['google']['authurl'] = 'https://accounts.google.com/o/oauth2/v2/auth';
$conf['auth']['oauth']['google']['tokenurl'] = 'https://oauth2.googleapis.com/token';
$conf['auth']['oauth']['google']['scopes'] = 'openid email profile';

GitHub OAuth Configuration

1. Register OAuth app in GitHub Settings > Developer Settings
2. Set callback URL to https://yourserver/wiki/lib/plugins/oauth/github.php
3. Configure:

<?php
$conf['authtype'] = 'oauth';
$conf['auth']['oauth']['github']['client_id'] = 'your-client-id';
$conf['auth']['oauth']['github']['client_secret'] = 'your-client-secret';
$conf['auth']['oauth']['github']['authurl'] = 'https://github.com/login/oauth/authorize';
$conf['auth']['oauth']['github']['tokenurl'] = 'https://github.com/login/oauth/access_token';
$conf['auth']['oauth']['github']['scopes'] = 'user:email';

SAML Authentication

SAML (Security Assertion Markup Language) is an enterprise SSO protocol.

Installing SAML Plugin

cd /var/www/html/wiki/lib/plugins/
wget https://github.com/username/dokuwiki-plugin-saml/archive/master.zip
unzip master.zip
mv dokuwiki-plugin-saml-master saml

Basic Configuration

<?php
// conf/local.php
$conf['authtype'] = 'saml';

$conf['auth']['saml']['idp']['entityId'] = 'https://idp.example.com/metadata';
$conf['auth']['saml']['idp']['singleSignOnService'] = 'https://idp.example.com/sso';
$conf['auth']['saml']['idp']['x509cert'] = 'MIID...base64-encoded-cert...';
$conf['auth']['saml']['sp']['entityId'] = 'https://yourserver/wiki/saml/metadata';
$conf['auth']['saml']['sp']['assertionConsumerService'] = 'https://yourserver/wiki/saml/acs';
$conf['auth']['saml']['mapping']['username'] = 'uid';
$conf['auth']['saml']['mapping']['email'] = 'email';
$conf['auth']['saml']['mapping']['groups'] = 'memberOf';

MySQL Authentication

For organizations that maintain user data in a MySQL database:

<?php
// conf/local.php
$conf['authtype'] = 'mysql';

$conf['auth']['mysql']['server'] = 'localhost';
$conf['auth']['mysql']['user'] = 'dokuwiki';
$conf['auth']['mysql']['password'] = 'password';
$conf['auth']['mysql']['database'] = 'dokuwiki';
$conf['auth']['mysql']['selectUser'] = 'SELECT user, pass, name, email FROM users WHERE user=%{user}';
$conf['auth']['mysql']['selectGroups'] = 'SELECT group FROM groups WHERE user=%{user}';

Troubleshooting Authentication

Debug Mode

Enable debug logging for authentication:

<?php
// conf/local.php
$conf['auth_debug'] = 1;

Debug output appears in the PHP error log.

Common Issues

Common Mistakes

1. Not enabling TLS for LDAP: Passwords transmitted in plaintext over LDAP without TLS. Always use LDAPS (port 636) or STARTTLS.
2. Mixing authentication backends: Only one authentication backend can be active at a time. The $conf['authtype'] setting determines which one is used.
3. Not testing the connection before enabling: A misconfigured LDAP or OAuth setup can lock all users out. Test the connection from the command line first.
4. Ignoring SSL certificate validation: Self-signed certificates cause LDAP STARTTLS failures. Add the CA certificate to the server's trust store.
5. Forgetting to update user mapping: AD and LDAP return different attribute names. If your wiki shows usernames instead of full names, the name mapping is incorrect.

Practice Questions

1. What configuration changes are needed to switch DokuWiki from plain-text to LDAP authentication?
2. How does OAuth authentication differ from LDAP, and when would you choose one over the other?
3. What is the purpose of the mapping configuration in LDAP authentication?
4. Challenge: Design an authentication architecture for an organization with 500 employees. The organization uses Active Directory for Windows logins, Google Workspace for email, and needs single sign-on across all systems including DokuWiki. Compare three approaches: LDAP against AD, OAuth with Google, and SAML with an identity provider. Recommend one approach with justification, and write the complete configuration for the chosen approach including all necessary settings in local.php.

FAQ

Mini Project

Goal: Set up an external authentication system for your wiki.

1. If you have an LDAP or AD server, configure DokuWiki to authenticate against it
2. If you do not have LDAP/AD, set up OAuth with a free provider (GitHub or Google)
3. Register test users in the external system
4. Verify that test users can log in to DokuWiki
5. Configure ACL rules using groups from the external system
6. Test that group-based permissions work with externally authenticated users
7. Document the authentication configuration and troubleshooting steps

What's Next

Authentication controls who can access your wiki. Now learn spam protection to keep your wiki clean from automated abuse.