DokuWiki ACL Basics — Permission Levels, acl.auth.php, and Access Rules

In this tutorial, you'll learn the basics of DokuWiki's Access Control List (ACL) system, including permission levels, how to write ACL rules in acl.auth.php, and how to configure permissions for users and groups.

What You'll Learn

• What ACL is and why it matters
• The four permission levels (1, 4, 8, 16)
• Writing ACL rules in conf/acl.auth.php
• Scope: global, namespace, and page-level rules
• User and group permissions
• Testing ACL rules
• Common ACL patterns

Why It Matters

Without ACL, your wiki is either completely open (anyone can edit) or completely closed (only admins). ACL lets you create fine-grained access control. You can make certain namespaces public, others team-only, and others admin-only. Understanding ACL is essential for any wiki that has multiple editors or sensitive content.

Real-World Use

A law firm uses DokuWiki for case documentation. The public: namespace is accessible to everyone. The cases: namespace requires login. Specific case pages within cases: are restricted to the legal team handling that case. The hr: namespace is restricted to HR staff only. ACL rules enforce these boundaries automatically — no manual permission management needed.

Learning Path

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

What is ACL?

ACL (Access Control List) is a system that defines who can do what on your wiki. In DokuWiki, ACL rules are stored in conf/acl.auth.php.

Each rule specifies three things:

1. Scope: Which page or namespace the rule applies to
2. Principal: Which user or group the rule is for
3. Permission level: What they are allowed to do

Permission Levels

DokuWiki defines four permission levels:

Permission levels are cumulative. A user with level 8 can read (1), create (4), and edit (8). They cannot delete (16).

The special level 0 means "no access" — the user cannot read or do anything with the scope.

The ACL File Format

ACL rules are written in conf/acl.auth.php. Each line has three fields:

scope     principal     permission

Example ACL File

# conf/acl.auth.php
# Format: scope principal permission

# Global rules (affect entire wiki)
*                       @ALL            @1          # Everyone can read
*                       @user           @8          # Logged-in users can edit

# Admin group has full access to everything
*                       @admin          @16         # Admins have all permissions

# Namespace-specific rules
@internal               @ALL            @0          # Internal namespace hidden from everyone
@internal               @staff          @16         # Staff can access internal namespace
@hr                     @hr-team        @16         # HR team manages HR namespace

# Page-specific rule
@pages:salary-review    @hr-managers    @16         # Only HR managers see salary reviews

# Deny a specific user
start                   baduser         @0          # Block baduser from the start page

Scope Patterns

• * — All pages and namespaces (global)
• @namespace — All pages in a namespace and its sub-namespaces
• @namespace:sub — All pages in a specific sub-namespace
• namespace:page — A specific page

Principal Patterns

• @ALL — Everyone, including unauthenticated visitors
• @user — All logged-in users
• @groupname — All users in a specific group
• username — A specific user

How ACL Rules Are Evaluated

When a user tries to access a page, DokuWiki:

1. Collects all ACL rules that apply to the user and the page
2. Orders them by specificity (most specific scope wins)
3. Returns the permission level from the most specific match

Rule Priority (Most Specific Wins)

1. Page-specific rule for the exact page
2. Page-specific rule for a parent page (not applicable in DokuWiki)
3. Sub-namespace rule (@namespace:sub)
4. Parent namespace rule (@namespace)
5. Global rule (*)

If two rules have the same specificity, the more restrictive permission (lower number) wins.

Enabling ACL

ACL is enabled by default in new installations. To verify or enable it:

<?php
// conf/local.php
$conf['useacl'] = 1;            // Enable ACL
$conf['autolang'] = 'en';       // Language for login screen
$conf['superuser'] = '@admin';  // Group with full access
$conf['manager'] = '@staff';    // Group with manager access (delete/upload)

The superuser group has unrestricted access — they bypass all ACL rules.

Testing ACL Rules

DokuWiki provides an ACL test page in the admin panel:

1. Navigate to Admin > Access Control List Management
2. Enter a page ID and a username
3. Click "Check" to see which permissions apply

You can also test from the command line using a script or by examining the ACL file directly.

Common ACL Patterns

Public Read, Registered Edit

*                       @ALL            @1          # Anyone can read
*                       @user           @8          # Registered users can edit

This is the most common pattern for team wikis. Visitors read without logging in. Editors authenticate to make changes.

Private Wiki

*                       @ALL            @0          # No public access
*                       @user           @8          # Registered users can read and edit

All content requires login. Visitors see only the login page.

Departmental Isolation

*                       @ALL            @1          # Everyone can read
*                       @user           @8          # Users can edit
@engineering            @engineers      @16         # Only engineers manage engineering pages
@hr                     @hr-team        @16         # Only HR manages HR pages

Each department has its own namespace with restricted edit access.

Public Wiki with Protected Pages

*                       @ALL            @8          # Anyone can read and edit
@internal               @ALL            @0          # Internal pages hidden
@internal               @admin          @16         # Only admins access internal pages

Common Mistakes

1. Not enabling ACL: If $conf['useacl'] is set to 0, all ACL rules are ignored and everyone has full access. Always verify ACL is enabled.
2. Using @ALL with level 16: Granting @ALL @16 gives everyone (including anonymous users) full admin access. Never use this pattern.
3. Confusing scope order: * at the end of the file overrides earlier rules because DokuWiki reads the last matching rule. Order matters.
4. Forgetting the superuser: If you lock yourself out (set @ALL @0 without a superuser account), you cannot access the admin panel. Always define $conf['superuser'].
5. Applying page-level rules when namespace rules would work: Page-level rules are harder to maintain at scale. Use namespace-level rules unless you need page-specific exceptions.

Practice Questions

1. What are the four DokuWiki permission levels, and what actions does each grant?
2. How would you write an ACL rule that allows only users in the "editors" group to edit pages in the docs: namespace?
3. What happens when multiple ACL rules apply to the same user and page, and which rule takes priority?
4. Challenge: Design an ACL configuration for a company wiki with the following requirements: Anyone can read the wiki. Registered users can edit. The hr: namespace is visible only to HR team members. The hr:salaries sub-namespace is visible only to HR managers. The engineering: namespace is editable only by the engineering team. The admin group has full access to everything. Block a specific user named "former-employee" from all namespaces. Write the complete acl.auth.php file and explain each rule.

FAQ

Mini Project

Goal: Set up a complete ACL configuration for a multi-department wiki.

1. Enable ACL in conf/local.php if not already enabled
2. Create an acl.auth.php file with the following rules:
   • Public read access for all pages
   • Edit access for logged-in users
   • Admin group has full access to everything
   • A team: namespace with edit access restricted to a specific group
   • An internal: namespace hidden from all non-admin users
3. Create test user accounts in different groups
4. Test that each user has the correct permissions for each namespace
5. Test that a blocked user cannot access restricted pages
6. Document your ACL configuration

What's Next

ACL rules control access. Now learn how to manage users and groups in DokuWiki's authentication system.