DokuWiki User Management — Adding Users, Groups, and Authentication Backends

In this tutorial, you'll learn how to manage users in DokuWiki, including adding and removing users, creating groups, configuring authentication backends, and enabling user self-registration.

What You'll Learn

• The users.auth.php file format
• Adding users through the admin panel
• Adding users manually
• Creating and managing groups
• Authentication backends overview
• Enabling user self-registration
• Password management and reset

Why It Matters

User management is the foundation of your wiki's security. Every user needs an account, a password, and group memberships that determine what they can do. Without proper user management, you have two extremes: either everyone is an admin, or you spend all your time creating accounts manually. Understanding the user system lets you scale your wiki from a single-person project to a hundred-editor knowledge base.

Real-World Use

An IT team of 15 engineers uses DokuWiki for documentation. When a new engineer joins, the team lead creates an account through the admin panel, assigns them to the "engineers" group, and the new hire immediately has edit access to the engineering namespace. When an engineer leaves, their account is disabled. The Process takes 30 seconds.

Learning Path

flowchart LR
  A[ACL Basics] --> B[User Management]
  B --> C[Advanced ACL]
  C --> D[Authentication]
  D --> E[Spam Protection]
  E --> F[Plugin System]

The users.auth.php File

DokuWiki stores user accounts in conf/users.auth.php. Each line represents one user:

username:passwordhash:Full Name:email@example.com:group1,group2

Fields separated by colons:

1. Username: Login name (lowercase, no spaces)
2. Password hash: bcrypt hash of the password
3. Full name: Display name
4. Email: User's email address
5. Groups: Comma-separated list of groups

Example file:

admin:$2y$10$abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUV:Admin User:admin@example.com:admin
jdoe:$2y$10$1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN:John Doe:john@example.com:user,engineers
asmith:$2y$10$zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMNOPQRSTUV:Alice Smith:alice@example.com:user,hr

The password hash is generated using PHP's password_hash() function. You cannot write the hash manually — use the admin panel or a script.

Adding Users Through the Admin Panel

1. Log in as an admin
2. Go to Admin > User Manager
3. Click "Add User"
4. Fill in: Username, Full Name, Email, Password, Groups
5. Click "Add"

The user is immediately active and can log in.

Adding Users Manually

When you need to add users in bulk or do not have web access, add them directly to users.auth.php:

# Generate a bcrypt hash for a password
php -r "echo password_hash('mypassword', PASSWORD_BCRYPT);"

Then add the line to users.auth.php:

newuser:$2y$10$generatedhash:New User:newuser@example.com:user

Be careful with manual editing — a syntax error in users.auth.php can prevent all logins.

Bulk User Import

For importing many users at once, write a script:

<?php
// import-users.php
// Run from command line: php import-users.php

$users = [
    ['alice', 'password123', 'Alice Smith', 'alice@example.com', 'user,engineering'],
    ['bob',   'password456', 'Bob Jones',   'bob@example.com',   'user,engineering'],
    ['carol', 'password789', 'Carol White', 'carol@example.com', 'user,hr'],
];

$lines = [];
foreach ($users as $user) {
    $hash = password_hash($user[1], PASSWORD_BCRYPT);
    $lines[] = implode(':', [$user[0], $hash, $user[2], $user[3], $user[4]]);
}

file_put_contents('conf/users.auth.php', implode("\n", $lines) . "\n", FILE_APPEND);
echo "Imported " . count($users) . " users.\n";

Run this script from your DokuWiki directory. It appends new users to the existing file.

User Groups

Groups are collections of users with shared permissions. They are defined in conf/users.auth.php as the group field.

Common Group Structure

# Group naming conventions
admin      # Full access (defined in ACL)
user       # Basic access (default for all users)
engineering # Engineering department
hr         # HR department
editors    # Content editors

Group Assignment

Users can belong to multiple groups. Group memberships are stored in the user record, not in a separate file.

Default Groups

• admin: Typically the superuser group (configured in local.php)
• user: All authenticated users (referenced in ACL as @user)

Authentication Backends

DokuWiki supports multiple authentication backends for user storage and verification.

Plain Text (Default)

The default backend stores users in conf/users.auth.php. It is simple and file-based.

<?php
// conf/local.php (default settings)
$conf['authtype'] = 'plain';     // Plain text authentication
$conf['auth']['plain']['usersfile'] = 'conf/users.auth.php';

MySQL Backend

For larger wikis, store users 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';

Other Backends

DokuWiki supports: LDAP, Active Directory, PgSQL (PostgreSQL), and custom authentication plugins. You will learn about these in Lesson 18.

User Self-Registration

To allow users to create their own accounts:

1. Go to Admin > Configuration Manager
2. Find the "autopasswd" setting and enable it
3. Find "disableactions" and remove "register" from the list

<?php
// conf/local.php
$conf['autopasswd'] = 1;          // Allow password change

When self-registration is enabled, a "Register" link appears on the login page. Users fill in a form with username, full name, and email. They receive their password via email (if mail is configured) or see it on screen.

Registration Workflow

1. User clicks "Register"
2. Fills in the form
3. Account is created
4. Password is either emailed or shown once
5. User logs in with the new account

Password Management

Changing Passwords

Users can change their own passwords from the profile page (link next to username).

Admins cannot view existing passwords but can reset them:

1. Go to Admin > User Manager
2. Find the user
3. Click "Modify" and enter a new password

Password Policy

DokuWiki does not enforce password complexity by default. You can add password policy plugins for this.

Forgotten Passwords

If $conf['autopasswd'] is enabled, users can request a password reset from the login page. The system generates a new password and emails it to the user.

User Deletion

To delete a user:

1. Go to Admin > User Manager
2. Find the user
3. Click "Delete"

The user is removed from users.auth.php. The user's page contributions remain (they are attributed to the username, which becomes an orphan reference).

To disable a user without deleting (preserving attribution):

• Remove the user from all groups
• Add them to a "disabled" group with @ALL @0 ACL rules

Common Mistakes

1. Editing users.auth.php with incorrect syntax: A single malformed line can break all authentication. Always back up the file before editing manually.
2. Not hashing passwords when adding users manually: Passwords must be bcrypt hashed. Adding a plain-text password prevents the user from logging in.
3. Creating too many groups: 10+ groups make ACL rules hard to manage. Use 3-5 groups (admin, user, department-specific) and assign users to multiple groups as needed.
4. Forgetting to set a superuser: If no user is in the superuser group, no one can manage ACL or users. Always ensure at least one admin user exists.
5. Enabling self-registration without spam protection: Open registration invites spam bots. Combine with CAPTCHA or email verification.

Practice Questions

1. What fields are stored in conf/users.auth.php, and what delimiters separate them?
2. How do you add a user in bulk using a PHP script? Write the key steps.
3. What is the difference between the "plain" authentication backend and the MySQL backend?
4. Challenge: Write a user management script that: imports 20 users from a CSV file (username, full name, email, group), generates bcrypt passwords for each, appends them to users.auth.php, creates a separate output file with username-password pairs for distribution, and verifies that all imported users can authenticate. Include error handling for duplicate usernames.

FAQ

{{< faq "How do I reset the admin password?" "If you have file access, edit conf/users.auth.php and replace the password hash with a new one generated by php -r \"echo password_hash('newpassword', PASSWORD_BCRYPT);\". If you do not have file access, use the password reset feature on the login page if autopasswd is enabled." >}}

Mini Project

Goal: Set up user management for a multi-team wiki.

1. Create 5 user accounts through the admin panel: 1 admin, 2 engineering, 2 marketing
2. Create 3 groups: admin, engineering, marketing
3. Add each user to the appropriate group
4. Configure ACL rules so engineering can edit the "engineering" namespace and marketing can edit the "marketing" namespace
5. Test each user's access by logging in as them
6. Enable user self-registration
7. Register a new user through the registration form
8. Test that the new user has correct default permissions

What's Next

Now you can manage users. Learn advanced ACL techniques for namespace-level rules, inheritance, and debugging.