[Backport 13.4] [FEATURE] How to create administrator accounts (#664)

* [FEATURE] How to create administrator accounts Preparing the structure for additional backend user and administration topics. Releases: main, 13.4, 12.4 * Apply suggestions from code review Co-authored-by: Stefan Frömken <froemken@gmail.com> --------- Co-authored-by: lina.wolf <lwolf@w-commerce.de> Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> Co-authored-by: Stefan Frömken <froemken@gmail.com>
TYPO3-Documentation · Jan 28, 2025 · 093d452 · 093d452
1 parent c002462
commit 093d452
Show file tree

Hide file tree

Showing 10 changed files with 230 additions and 2 deletions.
diff --git a/Documentation/Administration/BackendUsers/Administrator.rst b/Documentation/Administration/BackendUsers/Administrator.rst
@@ -0,0 +1,146 @@
+:navigation-title: Administrator
+
+..  include:: /Includes.rst.txt
+..  _backend-users-admin:
+
+===========================
+TYPO3 backend administrator
+===========================
+
+Each administrator that uses the TYPO3 backend should have their own personal
+backend user account. This allows you to see who made which changes later on.
+
+The administrator account that was automatically created for you during
+`Installation <https://docs.typo3.org/permalink/t3start:installation-index>`_
+has the widest rights possible and is a System Maintainer. The System Maintainer
+is an Administrator who can also see and use the section
+`Admin Tools <https://docs.typo3.org/permalink/t3start:admin-tools>`_ in the
+backend.
+
+..  tip::
+    If your Backend User account does not seem to work for some reason, check
+    chapter `Troubleshooting common TYPO3 backend login
+    problems <https://docs.typo3.org/permalink/t3start:troubleshooting-backend-login>`_.
+
+..  contents:: Table of Contents
+    :local:
+    :depth: 1
+
+..  _backend-users-admin-creation:
+
+Creating a TYPO3 backend administrator
+======================================
+
+There are 3 ways to create a new TYPO3 backend administrator:
+
+..  contents:: Table of Contents
+    :local:
+    :depth: 1
+
+..  _backend-users-admin-cli:
+
+Create an administrator using a console command
+-----------------------------------------------
+
+In DDEV or on a server if you can use the console there is a console
+command to create a new administrator:
+
+..  tabs::
+
+    ..  group-tab:: DDEV
+
+        ..  code-block:: bash
+
+            ddev typo3 backend:user:create
+
+    ..  group-tab:: On server
+
+        ..  code-block:: bash
+
+            vendor/bin/typo3 backend:user:create
+
+When prompted answer that you want to create an administrator. If they should
+also be a system maintainer, answer yes during the prompt.
+
+..  _backend-users-admin-backend-module:
+
+Using the backend module "Backend Users" to create admins
+---------------------------------------------------------
+
+The first administrator got created for you during
+`Installation <https://docs.typo3.org/permalink/t3start:installation-index>`_.
+
+When you log into the backend (See `Backend login <https://docs.typo3.org/permalink/t3start:backend-login>`_)
+you can go to module `Backend Users <https://docs.typo3.org/permalink/t3start:system-modules-backend-users>`_
+and create a new administrator there.
+
+..  figure:: /Images/ManualScreenshots/BackendUser/CreateUser.png
+    :alt: Screenshot of the "Backend Users" module demonstrating the location of the "Create new backend user" button in the module header
+
+    Open the module :guilabel:`System > Backend Users` and click on "Create new backend user"
+
+When creating the user check the "Admin" option:
+
+..  figure:: /Images/ManualScreenshots/BackendUser/CreateAdmin.png
+    :alt: The Admin option is the first option in the tab "General" in the backend user edit form
+
+    When you check the Admin option the form needs to reload once. Answer the dialogue with "OK".
+
+You can :ref:`Grant System Maintainer rights <backend-users-system-maintainer>`
+in the Admin Tools later on.
+
+..  _backend-users-admin-install-tool:
+
+Using the Install Tool to create an administrator
+-------------------------------------------------
+
+Access the Install Tool at `https://my-site.ddev.site/typo3/install.php` using
+the Install Tool password defined during the installation process.
+
+..  figure:: /Images/ManualScreenshots/BackendUser/InstallTool.png
+    :alt: The Install Tool: Create Administrative User, Create new administrative users and grant them system maintainer privileges (optional).
+
+    In the module "Maintenance" module use the button "Create Administrator".
+
+If they should be a System Maintainer check the box.
+
+..  _backend-users-system-maintainer:
+
+Granting System Maintainer rights
+=================================
+
+..  note::
+    You must be logged in with a System Maintainer account or use the
+    Install Tool to grant System Maintainer rights. In
+    `Application context Development <https://docs.typo3.org/permalink/t3start:application-context>`_
+    all backend administrators can use the module.
+
+Using the module :guilabel:`Admin Tools > Settings` and card
+"Manage System Maintainers Access" you can manage which administrator accounts
+should be granted "System Maintainer" rights.
+
+..  figure:: /Images/ManualScreenshots/BackendUser/ManageSystemMaintainers.png
+    :alt: "Manage System Maintainers" window in the Admin Tools.
+
+    Disabled backend admins are marked with [DISABLED], you can choose them any way.
+
+On saving the changes are written to file :file:`config/system/settings.php`
+therefore this file needs to be writable.
+
+If your installation also has a file called :file:`config/system/additional.php`
+the settings can be overridden here. In this case changes you make in the
+Admin Tools do not take effect.
+
+A setting overriding the System Maintainer list could look like this:
+
+..  code-block:: php
+    :caption: config/system/additional.php
+
+    $GLOBALS['TYPO3_CONF_VARS']['SYS']['systemMaintainers'] => [
+        1,
+        3,
+        42
+    ];
+
+This setting is also documented in
+:ref:`systemMaintainers <t3coreapi:confval-globals-typo3-conf-vars-sys-systemmaintainers>`.
diff --git a/Documentation/Administration/BackendUsers/Index.rst b/Documentation/Administration/BackendUsers/Index.rst
@@ -0,0 +1,43 @@
+:navigation-title: Backend Users
+
+..  include:: /Includes.rst.txt
+
+..  _backend-users:
+
+============================================
+Creating and configuring TYPO3 backend users
+============================================
+
+Each person that uses the TYPO3 backend should have their own personal backend
+user account.
+
+The user that was automatically created for you during
+`Installation <https://docs.typo3.org/permalink/t3start:installation-index>`_
+has the widest rights possible and is a System Maintainer. The System Maintainer
+is an Administrator who can also see and use the section
+`Admin Tools <https://docs.typo3.org/permalink/t3start:admin-tools>`_ in the
+backend.
+
+..  tip::
+    If your Backend User account does not seem to work for some reason, check
+    chapter `Troubleshooting common TYPO3 backend login
+    problems <https://docs.typo3.org/permalink/t3start:troubleshooting-backend-login>`_.
+
+..  toctree::
+    :hidden:
+    :titlesonly:
+    :glob:
+
+    *
+
+..  card-grid::
+    :columns: 1
+    :columns-md: 2
+    :gap: 4
+    :class: pb-4
+    :card-height: 100
+
+    ..  card:: `Administrators <https://docs.typo3.org/permalink/t3start:backend-users-admin>`_
+
+        Create personal administrator accounts and mange them. Grant
+        System Maintainer permissions to administrators.
diff --git a/Documentation/Administration/Index.rst b/Documentation/Administration/Index.rst
@@ -0,0 +1,34 @@
+:navigation-title: Administration
+
+..  include:: /Includes.rst.txt
+
+..  _administration:
+
+==========================================
+Administration of your first TYPO3 project
+==========================================
+
+In this chapter you will:
+
+*   Learn how to create and mange backend user.
+
+..  card-grid::
+    :columns: 1
+    :columns-md: 2
+    :gap: 4
+    :class: pb-4
+    :card-height: 100
+
+    ..  card:: Backend User Management
+
+        Each person (administrator or editor) that uses the TYPO3 backend should
+        have their own personal backend user account.
+
+        ..  card-footer:: :ref:`Backend Users <backend-users>` :ref:`Administrators <backend-users-admin>`
+            :button-style: btn btn-secondary stretched-link
+
+..  toctree::
+    :hidden:
+    :titlesonly:
+
+    BackendUsers/Index
diff --git a/Documentation/Images/ManualScreenshots/BackendUser/CreateAdmin.png b/Documentation/Images/ManualScreenshots/BackendUser/CreateAdmin.png
diff --git a/Documentation/Images/ManualScreenshots/BackendUser/CreateUser.png b/Documentation/Images/ManualScreenshots/BackendUser/CreateUser.png
diff --git a/Documentation/Images/ManualScreenshots/BackendUser/InstallTool.png b/Documentation/Images/ManualScreenshots/BackendUser/InstallTool.png
diff --git a/Documentation/Images/ManualScreenshots/BackendUser/ManageSystemMaintainers.png b/Documentation/Images/ManualScreenshots/BackendUser/ManageSystemMaintainers.png
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -94,6 +94,7 @@ system and detailed information on how to install TYPO3.
     Concepts/Index
     Installation/Index
     FirstProject/Index
+    Administration/Index
     Troubleshooting/Index
     Extensions/Index
     NextSteps/Index

diff --git a/Documentation/Troubleshooting/BackendLogin.rst b/Documentation/Troubleshooting/BackendLogin.rst
@@ -11,6 +11,10 @@ The following errors can happen during backend login:
 
 ..  contents::
 
+..  tip::
+    `Creating a TYPO3 backend administrator <https://docs.typo3.org/permalink/t3start:backend-users-admin-creation>`_
+    is a solution if you lost the password or user name of your administrator account.
+
 ..  _troubleshooting-login-reload:
 
 Login page reloads without error
@@ -31,7 +35,7 @@ Login page reloads without error
 ===========================
 
 *   Check if the username and password are correct.
-*   Try to create a :ref:`new administrative user <t3coreapi:troubleshooting-backend-admin-password>`
+*   Try to `Create a new backend administrator <https://docs.typo3.org/permalink/t3start:backend-users-admin-creation>`_
     and use that one.
 
 ..  _troubleshooting-login-white-screen:

diff --git a/Documentation/Troubleshooting/WebServer.rst b/Documentation/Troubleshooting/WebServer.rst
@@ -18,7 +18,7 @@ You can find detailed information on the following topics in TYPO3 Explained:
 
     ..  card:: :ref:`TYPO3 <t3coreapi:troubleshooting-typo3>`
 
-        *   :ref:`Reset Backend Administrative User Passwords <t3coreapi:troubleshooting-backend-admin-password>`
+        *   `Creating a TYPO3 backend administrator <https://docs.typo3.org/permalink/t3start:backend-users-admin-creation>`_
         *   :ref:`Reset The Install Tool Password <t3coreapi:troubleshooting-install-tool-password>`
         *   :ref:`Enabling Debug Mode <t3coreapi:troubleshooting-debug-mode>`
         *   :ref:`Caching <t3coreapi:troubleshooting-caching>`