Professional Content Management

Free and open source, TYPO3 CMS is the most widely used enterprise-level CMS.

Test TYPO3 now:

TYPO3 live demo

Inspire people to share

Offer your skills and contribute to the project. The community is growing and does more than just coding. 

A Community Effort

TYPO3 CMS is an Open Source project managed by the TYPO3 Association.

The Project

Do you have a question?

Ask the community or a professional partner.

ACL Enhancements — Permission Sets in TYPO3

Categories: Budget idea, Development, Community Created by Łukasz Uznański
In this article, Łukasz Uznański outlines the design, development journey (including UX experiments and pitfalls), and practical scenarios for applying permission sets in both new and existing TYPO3 projects.

The Access Control Lists (ACL) Enhancements initiative introduces a file-based approach, with a user interface, to managing backend permissions in TYPO3. It builds upon previous efforts but redefines them with permission sets: deployable, versionable, and integrator-friendly configuration files. With the new ACL Enhancements (acl_enhancements) extension, permissions can be exported, imported, edited, and distributed across environments.

Key benefits include:

  • Consistency through a single source of truth
  • Deployable and version-controlled ACLs
  • Editor-friendly workflows for creating and managing presets
  • Extensibility via third-party extension presets and custom file writers
  • Debugging and auditing tools that provide visibility into permission usage

Background and Motivation

We wanted to make a standalone extension to give the community critical improvements to TYPO3 workflow. We rebased previous ACL-related work, extracted functionality from patches, and then extended compatibility to TYPO3 v13 and began developing additional features. 

The goal was to make permission sets usable in real life by the community.

What is a Permission Set?

A permission set is a file that fully describes ACL rules for a backend group. It represents all selections from the group’s configuration, stored outside the database.

  • Where it lives:
    • Configuration/PermissionSets/ inside any extension
    • config/permission-sets/ at the installation level (default export location)
       
  • Why it matters:
    • Enforces a single source of truth: if a field is managed by a permission set, it cannot also be modified in the database.
    • Keeps backend groups lightweight - they only reference permission sets.
    • Enables deployment and version control for ACLs, just like code.

Think of a permission set as infrastructure-as-code for TYPO3 ACLs.

A dark-themed user interface for managing permission presets. News editor and Translation - EN - editor are selected items on the left; Calendar editor and Content editor are available items on the right.
Screenshot showing permission sets.

Deployable and Versionable Permissions

Previously, ACLs existed only in the database, which limited portability and traceability. With ACL Enhancements:

  • Backend groups can import permission sets.
  • Editors can export existing groups as reusable presets.
  • Files can be committed to Git, reviewed in pull requests, and deployed across environments.

This transforms ACLs from database records into code assets. Permissions are now portable, auditable, and can be consistent between dev, staging, and production.

Example export file generated by the extension, which can be used as a set, imported, or attached to your extension:

label: 'All users' 
categories: { }
customoptions: { }
fileMounts: { } 
filePermissions:
  - readFolder
  - writeFolder
  - addFolder
  - renameFolder
  - moveFolder
  - copyFolder
  - deleteFolder
  - readFile
  - writeFile
  - addFile
  - renameFile
  - moveFile
  - copyFile
  - deleteFile 
languages: { }
mfaProviders: { }
modules:
  user_setup: true
resources: 
  pages:
    permissions:
      - read
  sys_file:
    permissions:
      - read
  sys_file_collection: 
    permissions:
      - read

Third-party Extension Permission Sets

Permission sets are not limited to project code. Extension authors can ship ACL presets for their own modules and tables, which ease general implementation of permissions in all TYPO3 projects.

  • Integrators don’t need to manually reconfigure ACLs after updates of extensions.
  • Extension ACLs evolve in sync with the code - always up to date.
  • Projects stay consistent without extra maintenance overhead.

This introduces a shared responsibility model: extension authors define the defaults, integrators decide how to if and how to use them. 

Development Journey: From Concept to Usable Features

Starting Point: Import Only

The original patch supported only importing permission sets - applying them to backend groups. This was powerful, but too limited. Editors couldn’t create or evolve sets themselves, and integrators had to manage files manually in IDEs.

Making it Editor-Friendly: Presets from Backend Groups

To improve usability, I introduced a Create preset button, which allows you to create presets out of the backend group.

  1. Select a backend group.
  2. Open a preset (fake backend group) TCA view. This is a form that looks like a group but hides irrelevant fields. Then add your own field and management options.

Choose to save or export the configuration as a YAML file in config/permission-sets/.

A dark-themed interface displays buttons labeled Close, Save, New, Delete, and Use as permission set template. Below, the heading reads: Edit Backend usergroup All users on root level.

This gives editors a way to migrate existing database-based groups to file-based permission sets.

UX Experiments: Modals vs. Dedicated Pages

At first, I tried attaching the fake TCA view inside a modal. It looked fancy, but its usefulness was questionable. TYPO3 UX guidelines also discourage putting logical views into modals.

I pivoted to opening presets in a new module instead. This solved navigation issues and made room for additional features like saving, exporting, and editing.

Export Workflow

Initially, both backend groups and permission sets had an export button that generated YAML files. While functional, this caused confusion: exporting from a group made little sense, since you aren’t exporting the group itself but a permission set.

Decision: Remove export from groups and keep it only in permission set context. This enforces clarity and aligns with the logical data model.

Screenshot of a web interface showing buttons labeled Go back, Save, Export, and Delete above the heading Permission set edit and a file path typo3-yaml-provider/system/all-users-1.
Screenshot showing the action icons for the workflow.

Backend Module: Full Management UI

To replace manual file editing, I built a dedicated backend module.

TYPO3 module menu item called "Permission Sets" with an icon showing a padlock and a human head in white on a green background.
Icon showing the backend module for Permission Sets.

Features include:

  • Listing permission sets across all directories
  • Creating new sets from scratch (via TCA view)
  • Duplicating sets (file cloning)
  • Removing sets (deletes file permanently)
  • Downloading sets for version control
  • Displaying metadata: identifier (provider/package/filename), creation date, last modification date, if it is used by backend groups
  • Showing usage count: how many backend groups use a given set
  • Warning about dirty state if a file is invalid or malformed
  • Show read only status for files not within global config directory
A dark-mode interface displays a List of presets table with columns for Title, Identifier, Usage, Creation time, and Modification time. Each row has edit, duplicate, and delete icon buttons on the right.
Screenshot of the Permission Sets backend module.

Technical challenges: working with files in TYPO3 backend was not trivial — handling directories, timestamps, and identifiers required custom logic. But this work was essential to make ACL Enhancements truly editor-friendly.

Additional functionalities

Preview of non-editable permission sets

The module offers read-only previews of permission sets. These cannot be edited in the UI but can be inspected in detail.

  • Shows metadata such as identifier, provider, and timestamps
  • Displays how many backend groups use the set
  • Allows direct navigation into backend groups

This prevents accidental changes while giving administrators full visibility into the impact of each set.

Field-level usage insights

When a backend field is locked because it’s managed by a permission set, the UI shows exactly:

  • Which permission set(s) manage that field
  • How overlapping sets interact with it
Screenshot showing a section titled Table permissions with tags [tables_select, tables_modify], and a message stating: This field is managed by selected permission sets: typo3-yaml-provider/system/all-users.
The message shown when a field is managed by a permission set.

Without this, debugging permissions is guesswork. With it, integrators can immediately see why a field is blocked and which set is responsible.

Backend group linkage

In addition to previews and field-level insights, the module also tracks which backend groups are connected to a given permission set.

  • Each preset lists all groups that reference it
  • Provides direct navigation into those groups from the preset view
  • Helps administrators understand dependencies before editing, duplicating, or removing a set
Screenshot showing the text: Used by following backend user groups: [usedIn] and a bullet point for Advanced editors [uid: 5] underneath.
The UI showing a permission set used by a particular backend group.

This feature is especially useful in large TYPO3 installations where multiple groups may depend on the same preset. It ensures administrators can safely evaluate changes without unintended side effects.

Extensibility Through File Writers

Permission sets default to YAML, but the system supports alternative file writers. Projects can implement JSON, XML, or other formats if needed. This makes the approach flexible and future-proof for integration into diverse CI/CD pipelines.

Planned Functionalities

ACL Enhancements is available as a public extension, and we aim to improve it together as a community. Third-party extension authors can provide their own permission sets, which would help drive adoption and normalize the use of ACL Enhancements across TYPO3. Here are some ideas for the future:

Compare Presets

Add a feature to compare two presets and visualize differences in their ACL configuration. This will help integrators quickly identify mismatches and decide whether a new permission set is needed or if an existing one can be reused.

Import ACL From Module

Introduce an import function that allows uploading ACL definitions from a TYPO3 backend module directly into the config/permission-sets/ (system directory). This provides a faster path for creating sets without manually exporting or editing files.

Permission Set Inheritance

Enable inheritance between permission sets. In practice:

  • The UI should block editing fields that come from an inherited set.
  • Permissions should display a note explaining why they are active (i.e. which parent set they came from).
    This helps prevent accidental overrides and gives clarity about source and hierarchy.

Replace Legacy Database ACLs

Add a mechanism to replace old DB-defined ACLs with new file-based sets. This would allow integrators to migrate legacy groups without manually rebuilding them, ensuring smoother adoption of deployable permissions.

New Set Wizard

Change the New button so it launches a wizard. The wizard would allow selecting one or more existing permission sets as templates, then copy them into a new one. This simplifies creating new sets by reusing existing configurations.

Binding Backend Groups to Files

Introduce binding between backend groups and permission sets. This means any change in the group would automatically update the linked file. Combined with revision tracking, this ensures that files stay in sync without requiring manual exports.

Overwrite or Save-as Prompt

When exporting a set, show a popup asking whether to overwrite the existing file or save it as a new file. By default, new files should follow the naming scheme [filename]-X, where the base name depends on the backend group title. This prevents accidental overwrites while providing predictable file names.

Conclusion

ACL Enhancements reshape TYPO3 permission handling:

  • Permission sets bring clarity and consistency.
  • Permissions become deployable, versionable, and extensible.
  • Editors and integrators get practical tools for management and debugging.
  • Extension authors can deliver ACLs with their packages.

This initiative bridges usability and infrastructure-as-code, making TYPO3 permissions flexible, maintainable, and future-proof, and the result of that initiative is standalone extension, which you can use in your project.

We encourage you to use the ACL Enhancements extension, give feedback, and report any issues.

Check out  ACL Enhancements on GitHub!

Trace the History of This Project

Additional contributors for this article

Latest news

Show more