DokuWiki Advanced ACL — Namespace Rules, Inheritance, and ACL Debugging

In this tutorial, you'll learn advanced ACL techniques in DokuWiki including namespace-level permission rules, how permissions inherit through sub-namespaces, debugging ACL rules, and designing complex permission scenarios for multi-department wikis.

What You'll Learn

• Namespace-level ACL rules in depth
• Permission inheritance from parent to child namespaces
• Overriding parent namespace rules
• ACL rule ordering and priority
• ACL debugging tools
• Complex permission scenarios
• Managing ACL for large wikis

Why It Matters

As your wiki grows, simple global ACL rules are not enough. You need department-specific namespaces, project-level access, and page-level exceptions. Understanding advanced ACL lets you create sophisticated permission structures without conflicts or security gaps. One wrong ACL rule can expose private content or lock out legitimate editors.

Real-World Use

A company has 50 teams using a shared wiki. Each team has a private namespace (teams:teamname:). Individual team members can edit their own namespace. Team leads can manage their namespace. HR can read all team namespaces for Compliance. Executives can read everything. No team can access another team's namespace. This is configured entirely through ACL rules — no manual permission management required.

Learning Path

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

Namespace-Level ACL in Depth

Namespace rules apply to all pages within that namespace and its sub-namespaces.

Rule Format

@namespace      principal       permission

Examples

# Engineering department
@engineering              @engineers        @16     # Engineers control engineering namespace
@engineering:api         @engineers        @16     # Override inherited rules for sub-namespace
@engineering:internal    @engineers-lead   @16     # Team leads only for internal sub-namespace

# Multi-level nested
@projects:project-alpha  @alpha-team       @16     # Specific project
@projects:project-beta   @beta-team        @16     # Another project

Creating a Pattern

A common pattern for team wikis:

*                       @ALL              @1      # Global read
*                       @user             @8      # Global edit
@teams                  @ALL              @0      # Team namespaces hidden
@teams:team-a           @team-a           @16     # Team A manages their namespace
@teams:team-b           @team-b           @16     # Team B manages their namespace
@teams                  @admin            @16     # Admins can access all teams

Permission Inheritance

ACL permissions inherit from parent to child namespaces.

How Inheritance Works

@engineering       @engineers   @16     # Rule A: Engineers control engineering
@engineering:api   @ALL         @8      # Rule B: Everyone can edit API docs

• Pages in engineering:start use Rule A (engineers only)
• Pages in engineering:api:start use Rule B (all users can edit)

The sub-namespace rule (Rule B) overrides the parent rule (Rule A) for that sub-namespace only.

Inheritance Chain

Namespace: projects:project-alpha:api

1. Check: projects:project-alpha:api (most specific)
2. Check: projects:project-alpha (parent)
3. Check: projects (grandparent)
4. Check: * (global)

First match wins.

Breaking Inheritance

To explicitly deny access to a sub-namespace that would otherwise inherit:

@internal           @ALL    @0      # Internal namespace: no one can read
@internal           @admin  @16     # Except admins

The @ALL @0 rule at the parent level blocks everyone. The @admin @16 rule at the same level grants access to admins. Because @0 is more restrictive than @16, the @0 rule takes priority for non-admin users.

ACL Rule Priority

When multiple ACL rules could apply to a single request, DokuWiki uses this priority order:

1. Exact page match (most specific)
2. Exact namespace match (child namespace)
3. Parent namespace match
4. Global match (*)

If two rules at the same level apply (e.g., @engineering @user @8 and @engineering @admin @16 for the same page), the more restrictive rule (lower number) takes priority.

ACL Order in acl.auth.php

Rules are evaluated from top to bottom. The last matching rule wins. This means you should place general rules first and specific exceptions after:

# General rules (placed first)
*               @ALL      @1
*               @user     @8
*               @admin    @16

# Exceptions (placed after)
@internal       @ALL      @0
@internal       @admin    @16

If you reversed the order (specific first, general after), the general rule would override the specific one.

ACL Debugging

Admin Panel ACL Test

1. Go to Admin > Access Control List Management
2. Scroll to "ACL Test"
3. Enter a page ID (e.g., projects:roadmap)
4. Enter a username
5. Click "Check"

The tool shows which ACL rules apply and what effective permission the user has.

Manual Debugging

To debug ACL issues manually:

1. Check the acl.auth.php file for syntax errors
2. Verify the rule scope prefixes (@ for namespace, no prefix for pages)
3. Check user group memberships in users.auth.php
4. Verify $conf['superuser'] and $conf['useacl'] settings in local.php

Common ACL Issues

Complex Permission Scenarios

Scenario 1: Project Isolation

Multiple projects with their own teams and a shared area.

# Global
*               @ALL      @1
*               @user     @8

# Project A
@projects:alpha         @alpha-team   @16
@projects:alpha         @ALL          @0    # Hide from non-team
@projects:alpha         @admin        @16   # Admins can see

# Project B
@projects:beta          @beta-team    @16
@projects:beta          @ALL          @0
@projects:beta          @admin        @16

# Shared area (visible to all teams)
@projects:shared        @user         @8

Scenario 2: Content Lifecycle

Draft content is hidden, published content is visible.

# Drafts
@drafts                 @ALL          @0
@drafts                 @editors      @16

# Published
@published              @ALL          @1
@published              @user         @8

Move pages from drafts: to published: when they are ready.

Scenario 3: Client Portals

Each client has a private portal namespace.

@clients:client-a       @client-a     @16
@clients:client-a       @ALL          @0
@clients:client-a       @admin        @16
@clients:client-b       @client-b     @16
@clients:client-b       @ALL          @0
@clients:client-b       @admin        @16

Each client's users can access only their own client namespace.

Managing ACL for Large Wikis

For wikis with hundreds of ACL rules:

Use a Consistent Format

# [Category: Global]
*           @ALL    @1
*           @user   @8

# [Category: Departments]
@engineering    @engineers  @16
@hr             @hr-team    @16
@marketing      @marketers  @16

# [Category: Projects]
@projects:alpha     @alpha-team   @16
@projects:beta      @beta-team    @16

Version Control

Keep acl.auth.php in version control with descriptive commit messages:

Added ACL rules for new Client Portal namespace
  - @clients:client-c @client-c @16
  - @clients:client-c @ALL @0
  - @clients:client-c @admin @16

Regular Audits

Review ACL rules quarterly:

1. Remove rules for deactivated projects
2. Update group names for renamed departments
3. Check for conflicting rules
4. Verify superuser access is still valid

Common Mistakes

1. Overly broad namespace rules: @ALL @0 on a parent namespace blocks all sub-namespaces. Always test namespace rules with a non-admin user.
2. Conflicting rules at the same level: Two rules at the same scope with different permissions can produce unexpected results. The more restrictive (lower number) wins.
3. Not testing with a non-admin user: Admin users bypass ACL rules. Always test permissions as a regular user.
4. Relying on rule order when specificity would work: Instead of relying on "last match wins," make rules more specific to avoid order dependence.
5. Missing group definitions: An ACL rule referencing @nonexistent-group has no effect because the group has no members. Verify group names in users.auth.php.

Practice Questions

1. How does ACL permission inheritance work when a sub-namespace has no specific rules?
2. If @engineering @ALL @0 and @engineering:api @user @8 both apply, what permission does a regular user have in engineering:api:start?
3. Why should ACL rules be ordered from general to specific, and what happens if they are reversed?
4. Challenge: Design and implement ACL rules for a wiki with the following requirements: Public users can read docs: namespace only. Registered users can edit docs: but not delete. Team Alpha can read, edit, and delete their namespace teams:alpha but not teams:beta. Team Beta has the same for teams:beta. Admins have full access to everything. HR can read all team namespaces but not edit them. Each team has an internal sub-namespace visible only to that team. Write the complete ACL rules and test each scenario.

FAQ

Mini Project

Goal: Design and implement a complex ACL configuration.

1. Create a namespace structure: docs:, teams:alpha:, teams:beta:, internal:, shared:
2. Create user accounts for: admin, alice (team alpha), bob (team beta), and charlie (no team)
3. Write ACL rules for the scenario in the Practice Questions challenge
4. Test every user-permission combination (at least 10 tests)
5. Debug any failed tests and fix the rules
6. Document your ACL configuration with explanations for each rule
7. Add comments to the acl.auth.php file explaining the purpose of each section

What's Next

ACL controls access. Now explore authentication plugins for LDAP, Active Directory, OAuth, and SAML integration.