Study guide · Administration and Permissions
Who may do what? Permission concepts, reports and data transfer in TYPO3
A good permission concept decides whether an editorial team works safely and without frustration. Or whether, in the end, everybody is an administrator "because nothing works otherwise". On this page you plan the permissions for a client project step by step. After that you get to know the reports in the Reports module and see how to move content from one installation to another with the Import/Export extension.
The example: the Seetal holiday region
Your client is the tourism association Seetal holiday region. One TYPO3 installation runs two websites: the main site of the region and the site of the guest card "Seetal Card". These people will work in the backend:
- The marketing lead maintains all editorial content and approves it.
- The association's editors maintain pages and news on the main site.
- The local tourist offices maintain only the pages of their own town and their own image folder.
- The Seetal Card team works only on the second website.
- A translator edits only the English and French versions.
Later, interns join, and old hiking trail pages from TYPO3 6 have to be taken over.
Users, groups and administrators
TYPO3 strictly separates two kinds of users. Frontend users log in on the website, for example in a members' area. Backend users log in to the backend and maintain content. This page is about the second kind.
A backend user group bundles permissions. It defines which modules, tables, fields, pages and file folders its members may use. That way many users share the same permissions. Frontend groups are completely separate and only control who sees what on the website.
A user can belong to several groups, and groups can have subgroups. The user then receives the permissions of all of their groups combined, including those of the subgroups. Permissions are added up, never offset against each other. More groups mean more access.
Users and groups are managed in the module Administration > Users. Up to TYPO3 13 it was called "System > Backend Users". There you create them, filter them, compare them and switch into a user for testing. The User Settings, by contrast, only affect your own account.
Where do these records live? Backend users and groups are stored on the top level of the page tree, the root level with the ID 0. Only administrators may edit records there. Frontend users, by contrast, live in normal folders in the page tree.
A new user starts with nothing. Without the admin option, groups, mounts and page permissions, they see neither pages nor the Layout module. TYPO3 follows the principle "nothing is allowed until granted".
Administrators are the opposite. A user with the "Admin" option may do everything in the backend without any further permissions. Groups and page permissions do not apply to them. This is comparable to the root user on Unix. In the backend you recognize admin accounts by an orange icon. A System Maintainer is an administrator who may also use the system tools under System, such as Settings, Maintenance and Extensions.
Secure accounts belong in every permission concept:
- Every person gets their own account. Shared accounts such as "editorial" or "webmaster" blur who changed what. That is a security risk and also a problem under the GDPR.
- Only people who really need admin rights for development or operations get them. Experienced editors, so-called super users, do not get admin rights either, but suitable groups.
- Strong passwords and multi-factor authentication are a must, especially for admins.
- Temporary access, for example for interns, gets an expiration date. That way no forgotten accounts stay active. You review all accounts regularly.
What you can allow: access lists
TYPO3 knows four kinds of permissions for backend users: access lists, mounts for the page tree and files, page permissions and user TSconfig. Frontend groups are not among them. You set most permissions on the group, some also on the user.
The access lists control what a user may touch in the system at all:
- Modules: You choose which modules and submodules a user sees. That way an editor sees only what they need for their work.
- Dashboard widgets: Which widgets they may use on the dashboard.
- Tables: For each table you choose no access, read only, or read and write, for example for content elements or news. In TYPO3 14 this is collected in the field "Table permissions". The documentation calls the two lists behind it "Tables (listing)" for viewing and "Tables (modify)" for editing. Write access automatically includes read access.
- Page types: Which kinds of pages they may create.
- Excludefields: Fields that are hidden by default.
- Field values: Which content element types or plugins are explicitly allowed.
- Languages: Which languages they may edit.
The modules under Administration, such as Users, Permissions and Reports, and the modules under System are reserved for administrators. One exception is the Log, which you can also grant to editors.
Excludefields deserve a closer look. If a field is marked as "exclude" in the TCA, non-admins only see it once their group has it explicitly allowed. In the TYPO3 14 form the list is called "Allowed fields", in the documentation "Allowed excludefields". Admins always see all fields. That way you keep forms lean for editors.
Languages: With "Limit to languages" in the access lists, a user only edits records in the allowed languages. The Seetal translator gets English and French. If no language is selected, all languages are allowed. Records with the language "All" always remain editable.
User TSconfig is the fourth kind. It is configuration in TypoScript syntax that is attached to users or groups. You use it for "soft" settings: showing or hiding backend features, setting defaults, or requiring multi-factor authentication with auth.mfa.required. Page permissions, access lists and mounts are separate settings.
Mounts and page permissions
Mounts define which part a user gets to see:
- A DB mount is an entry point into the page tree. The user only sees this subtree. In the TYPO3 14 form the field is called "Page Tree Entry Points". It has nothing to do with the database itself or with exports.
- A file mount points to a folder in a file storage, for example the folder user_upload in fileadmin. It decides which folders a user can reach in the Media module. Allowed file types, by contrast, are set in the global configuration.
- A category mount opens up part of the category tree.
The user record has an option "Mount from groups", separately for DB mounts and file mounts. It is active by default, so the user takes over the mounts of their groups. If you switch it off, only the mounts set directly on the user apply.
Page permissions control what a user may do on a page. Much like files on Unix, every page has an owner, a group and permissions for owner, group and everybody. There are five page permissions:
- Show, that is viewing the page, with the value 1.
- Edit page, with the value 2.
- Delete page, with the value 4.
- New pages, that is creating subpages, with the value 8.
- Edit page content, with the value 16.
You set them in the module Administration > Permissions, called "System > Permissions" up to TYPO3 13. There you can apply them recursively to a whole subtree. Only administrators and the owner of a page may change its permissions.
Mount and page permission must fit together. The mount says which part of the tree is shown. The page permission says what you may do there. Without the "Show" permission nothing appears, despite the mount.
New pages: When an editor creates a page, they become its owner. As page group it gets the first group in their user record. If the wrong group is listed first, colleagues may not see the new page. With page TSconfig, in the area TCEMAIN.permissions, you can preset owner, group and permissions of new pages.
A permission concept in layers
The most important rule: you grant permissions through groups, not directly on the user. When something changes, the change applies to all members, and you can see where a permission comes from. Scattered settings on individual users are hard to keep track of. With groups you map roles such as "editor" or "proofreader" cleanly.
The documentation suggests three kinds of groups as a guideline. It is not a fixed TYPO3 standard, but a proven order.
- System groups control access to pages, categories and files: page permissions, DB mounts, category mounts and file mounts. They rarely change.
- ACL groups, short for access control list, control fine-grained permissions: modules, widgets, tables, fields and content types. They are usually the largest set of groups.
- Role groups such as "R_editor" bundle system and ACL groups into one role. They have no permissions of their own, only subgroups. Users only get role groups.
Prefixes in group names create an overview, because TYPO3 only sorts groups alphabetically. The documentation suggests, for example, "R_" for roles, "PG_" for page areas, "DBM_" for DB mounts, "FM_" for file mounts and "ACL_" for access lists. In the group's notes field you write what it is for.
An ACL group is a complete unit. If an editor should maintain news but not edit any other tables, their group needs:
- Access to the module Content > Records or to a dedicated news module.
- The news table in "Tables (listing)" and in "Tables (modify)".
- The required fields as allowed excludefields and, because of the images, permissions for the related files.
Access to the news folder itself, that is mount and page permissions, comes from system groups. Admin rights or the Install Tool are not needed for this.
Keep inheritance flat: TYPO3 does not limit the depth. The documentation recommends one or two levels, though. With deep chains, soon nobody knows where a permission comes from.
The concept for Seetal:
- In a workshop with the client, collect roles and tasks: who maintains which areas, content types and languages, and who approves?
- Build small groups: PG_seeburg and DBM_seeburg for the town's area, FM_seeburg for its image folder, ACL_news for news, and a language group for English and French.
- For the image storage shared by all websites, create a separate group with its own file mount.
- Build role groups such as R_office_seeburg and R_editor_seetalcard that only inherit the matching small groups.
- Set page permissions in the Permissions module to match the groups.
- Test with test users, document and review regularly.
If a client runs three brand websites in one installation, the same pattern applies. Each brand gets groups for pages and mounts. The shared image storage gets a group with its own file mount. Role groups such as R_editor_brand_a combine them. Proofreaders get a role that inherits all brands.
Testing and troubleshooting
You do not check permissions by asking for passwords. The module Administration > Users has tools for this:
- Switch to user: An admin logs in as this user and sees exactly their backend. The user menu then shows "SU" in front of the name, for a simulated user. With "Exit switch user mode" in the same menu, the admin returns to their own account.
- Compare: With the button "+ Compare" you put users or groups on a compare list and view them side by side. For groups, inherited permissions are shown as well.
- Since TYPO3 14 a detail view shows which permissions a group has in total. A filter shows the users who are currently logged in.
Incomplete permissions lead to empty page trees, missing fields or even error messages. That is why you test every role before the editorial team gets started.
Limits of the permission system
As a consultant you should know the limits before the client discovers them:
- Permissions add up. Every group can only add permissions. You cannot take a permission away with another group. A user in too many groups quickly has too much access.
- There is no level between admin and normal user. Anyone who should edit TypoScript, for example, needs admin rights. This intermediate level is missing on purpose, because TypoScript can be used to execute PHP code.
- Table and field permissions apply installation-wide. Whoever may edit news may do so in every folder they see through a mount. Permissions on individual records only exist through pages, folders and mounts.
- Complex inheritance becomes confusing. With deep chains it is hard to trace where a permission comes from.
- Admins bypass everything. That is why you do not make editors admins just to get something working.
Reports: status, records, content and log
The module Administration > Reports is reserved for administrators. It belongs to the system extension reports and, since TYPO3 14, shows its reports as an overview of cards. Other extensions can add their own reports and checks, for example the search solution EXT:solr.
The status report gives an overview of the state of the system. Among other things it checks PHP modules, directories and file permissions, the protection of the Install Tool, the encrypted connection and the setting for trusted host names. It also warns when old export files from Import/Export are lying around. The documentation recommends reviewing especially the security section regularly. It does not provide visitor statistics.
Extensions also report their checks here. The Redirects extension, for example, remembers when the command redirects:checkintegrity last ran. If that was more than 24 hours ago, the status report shows a notice. The 24 hours are the default and can be changed in the extension configuration. The list of redirect conflicts may then be outdated. So the command should run regularly, for example through the scheduler. The redirects themselves keep working.
Record Statistics count records across the whole installation, across all sites. You see, for example, the number of all pages, of translated, hidden and deleted pages, the page types, records per table, and backend users and groups. Records flagged as deleted, with deleted set to 1, are not counted. Only the figure for deleted pages lists them separately. Since TYPO3 14 the Record Statistics belong to Reports; before, they were in the database module.
Content Statistics have existed since TYPO3 14.2. The report lists all content element types with the number of times each is used, separated into visible and hidden elements. For each type it shows the related fields with field type, whether the field is required and whether it can be excluded through group permissions. A detail view lists the records of a type.
The log in the module Administration > Log shows recorded actions: logins and logouts, cache clearing, creating, changing and deleting records, file actions and errors. Filters help you search. For data protection reasons you clean up old entries regularly.
Together, the three reports deliver the system state and configuration hints, the size and structure of the records, and the use of content types. Visitor numbers, bounce rates or revenue are not part of it; there are separate analytics tools for that.
Export and import with impexp
The system extension Import/Export, impexp for short, exports pages and content from one TYPO3 installation and imports them into another. This includes records from many tables plus the linked files from fileadmin. Typical uses are distributions, training, demos and moves. Program code is not included: extensions and site packages do not travel along.
Formats: Exports are written as XML or in the T3D format, which is also available compressed. The CSV and JSON downloads in the Records module are a different feature.
How to use it: In the page tree, a right-click opens the context menu. Under "More options" you find "Export" and "Import", with the page already selected. On the command line there are the commands impexp:export and impexp:import with the same options. No PHP time limit applies there, unlike requests in the browser. That makes the command line especially suitable for large page trees.
Who may export and import? By default, only administrators. For editors you can enable both with user TSconfig, separately for export and import. They then only see pages they have access to themselves. Some options, such as forcing the original IDs, remain reserved for administrators.
IDs on import: By default TYPO3 assigns new IDs, that is new uids. It adjusts relations along the way: content stays on its pages, images stay on their elements. That way you can merge content from several sources. Optionally the IDs are kept. With the option "Update records", existing records with the same uid are updated instead of created again. Content outside the exported subtree stays unchanged.
Relations on export: If the export tool shows an orange exclamation mark next to a record, a relation will be lost. The related record lies outside the export, or its table is excluded. You then have two options.
- "Include relations to tables" takes the related records along, even if they lie outside the selected pages.
- "Use static relations for tables" only exports the reference. That fits categories or users that already exist in the target system with the same ID.
Before the import you prepare the target system. All required extensions are installed, and the database schema is up to date. Otherwise, data for missing tables is not imported. A backup of the target database lets you go back. The preview in the import module shows beforehand what will be created or updated.
Syncing staging and live: With "Update records" you can sync individual areas on purpose. For recurring exports you save templates, so-called presets. But impexp offers no automatic two-way sync in real time. Workspaces only work within one installation. For content workflows across several environments there are third-party solutions.
Security: Exports can contain sensitive or personal data. The documentation recommends three things:
- Deactivate the extension while you do not need it.
- Hide the export entry in the context menu with user TSconfig, using the setting contextMenu disableItems. This does not fully prevent exports, because there are other entry points.
- Protect the export folder. Exports are stored in fileadmin, in the folder user_upload, subfolder _temp_ and in it importexport. TYPO3 creates a .htaccess file there that blocks access. It only works on Apache, though. NGINX does not read .htaccess files, so there you block the folder in the server configuration.
Planning a content migration
In a relaunch or a system change, content elements, fields and structures often differ. Without planning, real damage looms:
- Content or relations get lost because the structures differ.
- Old URLs lead nowhere if redirects are missing. That hurts visitors and search engine rankings.
- Unexpected data protection issues come up, for example old user data that was carried over. Clarify what really has to be migrated instead of migrating everything blindly.
Different content needs different paths: pages and content elements often via impexp, media directly, custom records by script or by the extension's own import.
How well do old exports fit? The data structure of exports has barely changed since its beginnings. According to the documentation, it is sometimes possible to import content from a fifteen-year-old installation straight into a current TYPO3. That is often easier than updating an old installation version by version. Because of breaking changes, problems can occur, though. A fully working export and re-import is only guaranteed within the same major version. The older the source, the more rework.
- Inventory: which content types and what amounts are there?
- Choose a path for each content type and define how it maps to the new structure.
- Prepare the target system and make a backup.
- Run a test migration and check it with samples, counts, links and images.
- Run the final migration with a content freeze and set up redirects for the old URLs.
Key points
- Backend users receive the sum of the permissions of all their groups. Permissions add up and cannot be taken away by a group.
- Users and groups live on the root level and are managed in the module Administration > Users, page permissions in the module Administration > Permissions.
- A new user has no permissions. Admins have all of them and belong only in the hands of development and operations.
- Four kinds of permissions: access lists, mounts, page permissions and user TSconfig.
- A DB mount only shows something if the page permission "Show" is in place too.
- New pages belong to their creator and the creator's first group.
- Permissions only through groups: system groups, ACL groups and role groups, with prefixes and flat inheritance.
- Test with "Switch to user" and the compare feature in the Users module.
- Reports: the status report for the system state, Record Statistics for the records, Content Statistics for the use of content types.
- impexp exports records and files as XML or T3D, but no code. Re-import is only guaranteed within the same major version.
Terms
- ACL group
- Group with fine-grained permissions on modules, tables and fields.
- Administrator
- User with all permissions in the backend, to whom groups and page permissions do not apply.
- Category mount
- Part of the category tree that a user may access.
- DB mount
- Entry point into the page tree, called "Page Tree Entry Point" in TYPO3 14.
- Excludefield
- Field that must be explicitly allowed for non-admins.
- File mount
- Folder in a file storage that a user may access.
- impexp
- System extension for exporting and importing pages, records and files.
- Role group
- Group without permissions of its own that bundles other groups into a role.
- Page permissions
- Permissions per page for owner, group and everybody.
- System Maintainer
- Administrator with additional access to the system tools.
- T3D
- File format of impexp, also available compressed.
- User TSconfig
- Configuration for soft backend settings per user or group.