TYPO3-Documentation · linawolf · Oct 17, 2024 · Oct 17, 2024
diff --git a/Documentation/Administration/Index.rst b/Documentation/Administration/Index.rst
@@ -28,3 +28,10 @@ TYPO3 administration
         Composer <t3upgrade:migratetocomposer>`.
 
         :ref:`TYPO3 Upgrade Guide <t3upgrade:upgrading>`
+
+..  toctree::
+    :hidden:
+    :glob:
+
+    */Index
+    *
diff --git a/Documentation/Administration/PermissionsManagement/ExampleConfiguration/Index.rst b/Documentation/Administration/PermissionsManagement/ExampleConfiguration/Index.rst
@@ -0,0 +1,123 @@
+.. include:: /Includes.rst.txt
+
+.. index:: backend, acl, permissions, user groups, user management
+
+.. _example-configuration:
+
+============================================
+Example configuration of backend user groups
+============================================
+
+How backend user groups can be :ref:`categorized <_available-acl-options>`,
+and organized using :ref:`naming conventions <_naming-convention>`
+to distinguish their purpose or context as well as following best practice
+and more advanced examples of group structures for projects with a single or multisite setup
+are discussed.
+
+.. _single-site-structure:
+
+Backend groups’ structure for a small project
+==============================================
+
+When setting up backend groups and permissions for small, single-site projects
+future complexity should be considered. Organizing groups by best practice from the start
+makes future extension and maintenance easier.
+
+Consider a scenario where two role groups are required: one for general content management,
+named :samp:`Content Editor`, and one for survey management, named :samp:`Survey Manager`.
+
+The following conditions should be met:
+
+* Both roles should manage content in all languages
+* Both roles should perform any file operations
+* The Content Editor role has a dedicated file mount for organizing files
+* The Survey Manager role should have access to a dedicated file mount within the same file storage
+* The Content Editor role should be able to view files uploaded by users with the Survey Manager role, as they might need them for blog posts mentioning the surveys
+* The Content Editor role should manage all types of content, except for surveys
+* The Content Editor should have access to a dedicated branch in system categories
+* The Survey Manager role should only see the storage folder and the part of the pages tree where the surveys are listed and rendered
+* The Survey Manager role does not need access to any system categories
+
+With these requirements in mind, the backend groups structure can be planned.
+Following best practice of having :ref:`System Groups <_system-groups>`
+and :ref:`Access Control List Groups <_acl-groups>`, it could look like this:
+
+..  uml:: _backend-groups-simple-project.plantuml
+    :align: center
+    :width: 700
+
+Having defined all the required :samp:`System` and :samp:`Access Control List` groups,
+they can be combined to fulfill the :samp:`Content Editor` and :samp:`Survey Manager`
+role requirements.
+
+..  uml:: _backend-groups-simple-project-organized.plantuml
+    :align: center
+    :width: 700
+
+The :samp:`System` and :samp:`Access Control List (ACL)` groups serve as components
+that can be integrated into a larger entity, in this case, the role group.
+These role groups can then be assigned to users. As previously mentioned,
+permissions should only be assigned to users via role groups.
+
+.. _multisite-structure:
+
+Backend group structure for a multi-site project
+==================================================
+
+When creating backend user groups for a multi-site project, the approach is
+the same as that of smaller, :ref:`single-site projects <_single-site-structure>`.
+Adhering to recommended best practice from the start simplifies building the website
+and prepares for a more advanced setup.
+
+This scenario describes a project with three separate sites (a multi-site setup).
+There will be three distinct :samp:`Content Editors` roles, one for each site,
+along with other roles that will have cross-site access and permissions
+to manage content.
+
+The following conditions should be met:
+
+* Project has 3 separate sites: Website A, Website B, Website C
+* Project has one default language and one translation to English language
+* For each site there are separate Content Editor roles as they will have different permissions
+* Content Editor roles on Website A and Website C will have access to all languages, while the Content Editor role for Website B will have access only to the English language
+* Each Content Editor role  should have access to dedicated system categories branch
+* Each Content Editor role can manage general content elements
+* Content Editor role on Website A and C can manage news
+* Content Editor role on Website A and C can manage galleries
+* Content Editor role on Website A can manage use custom page types
+* Content Editor role on Website A can manage contact forms (send responses etc.)
+* Content Editor role on Website B can manage surveys
+
+Start by creating the necessary groups to form role groups. This includes system groups
+for each site and shared groups across different roles and sites. Next, define the
+ACL groups, which will be universally reusable for all role groups on any site.
+
+..  uml:: _backend-groups-multisite-project-1.plantuml
+    :align: center
+    :width: 700
+
+..  uml:: _backend-groups-multisite-project-2.plantuml
+    :align: center
+    :width: 700
+
+Groups specific to particular sites (e.g., page groups, database mounts) have
+been identified as well as the :samp:`shared groups`, which are universal,
+and reused across role groups. Use shared groups for
+for roles for single sites as well as for cross-site groups.
+
+The ACL groups could be further granulated, by separating out permissions
+for different content elements and dividing records’ related groups into multiple
+ones — for editing records, managing lists and details through plugins, etc.
+It is not done here to avoid overly complicating the diagram, which is already
+quite comprehensive. However, in your setup, it might be necessary to create
+more ACL groups, each responsible for a smaller set of permissions than those shown here.
+
+The desired backend groups structure and aggregation could look like this:
+
+..  uml:: _backend-groups-multisite-project-organized.plantuml
+    :align: center
+    :width: 700
+
+The key concept that you should grasp here is that small backend groups
+are combined to form a Role group. Role groups are the 'top' tier and only they
+can be assigned to users later on.
diff --git a/...n/PermissionsManagement/ExampleConfiguration/_backend-groups-multisite-project-1.plantuml b/...n/PermissionsManagement/ExampleConfiguration/_backend-groups-multisite-project-1.plantuml
@@ -0,0 +1,42 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "Website A" AS Website_A #line.dotted {
+  rectangle "PG_website_a" as PG_website_a #Application
+  rectangle "DBM_website_a" as DBM_website_a #Application
+  rectangle "DBM_website_a_news" as DBM_website_a_news #Application
+  rectangle "FM_website_a" as FM_website_a #Application
+  rectangle "CM_website_a" as CM_website_a #Application
+  PG_website_a -[hidden]-> DBM_website_a
+  DBM_website_a -[hidden]-> DBM_website_a_news
+  DBM_website_a_news -[hidden]-> FM_website_a
+  FM_website_a -[hidden]-> CM_website_a
+}
+
+rectangle "Website B" AS Website_B #line.dotted {
+  rectangle "PG_website_b" as PG_website_b #Application
+  rectangle "DBM_website_b" as DBM_website_b #Application
+  rectangle "DBM_website_b_news" as DBM_website_b_news #Application
+  rectangle "DBM_website_b_survey" as DBM_website_b_survey #Application
+  rectangle "FM_website_b" as FM_website_b #Application
+  rectangle "FM_website_b_survey" as FM_website_b_survey #Application
+  rectangle "CM_website_b" as CM_website_b #Application
+  PG_website_b -[hidden]-> DBM_website_b
+  DBM_website_b -[hidden]-> DBM_website_b_news
+  DBM_website_b_news -[hidden]-> DBM_website_b_survey
+  DBM_website_b_survey -[hidden]-> FM_website_b
+  FM_website_b -[hidden]-> FM_website_b_survey
+  FM_website_b_survey -[hidden]-> CM_website_b
+}
+
+rectangle "Website C" AS Website_C #line.dotted {
+  rectangle "PG_website_c" as PG_website_c #Application
+  rectangle "DBM_website_c" as DBM_website_c #Application
+  rectangle "FM_website_c" as FM_website_c #Application
+  rectangle "CM_website_c" as CM_website_c #Application
+  PG_website_c -[hidden]-> DBM_website_c
+  DBM_website_c -[hidden]-> FM_website_c
+  FM_website_c -[hidden]-> CM_website_c
+}
+@enduml
diff --git a/...n/PermissionsManagement/ExampleConfiguration/_backend-groups-multisite-project-2.plantuml b/...n/PermissionsManagement/ExampleConfiguration/_backend-groups-multisite-project-2.plantuml
@@ -0,0 +1,26 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "Shared System groups" AS Shared_System_Groups #line.dotted {
+  rectangle "FO_all" AS FO_all #Application
+  rectangle "L_all" AS L_all #Application
+  rectangle "L_english" AS L_english #Application
+  FO_all -[hidden]-> L_all
+  L_all -[hidden]-> L_english
+}
+
+rectangle "Shared ACL groups" AS Shared_ACL_Groups #line.dotted {
+  rectangle "ACL_content_elements" AS ACL_content_elements #Technology
+  rectangle "ACL_news" AS ACL_news #Technology
+  rectangle "ACL_gallery" AS ACL_gallery #Technology
+  rectangle "ACL_survey" AS ACL_survey #Technology
+  rectangle "ACL_contact_forms" AS ACL_contact_forms #Technology
+  rectangle "ACL_pages_custom" AS ACL_pages_custom #Technology
+  ACL_content_elements -[hidden]-> ACL_news
+  ACL_news -[hidden]-> ACL_gallery
+  ACL_gallery -[hidden]-> ACL_survey
+  ACL_survey -[hidden]-> ACL_contact_forms
+  ACL_contact_forms -[hidden]-> ACL_pages_custom
+}
+@enduml
diff --git a/...sionsManagement/ExampleConfiguration/_backend-groups-multisite-project-organized.plantuml b/...sionsManagement/ExampleConfiguration/_backend-groups-multisite-project-organized.plantuml
@@ -0,0 +1,70 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "Website A" #line.dotted {
+    rectangle "R_website_a_editor" as R_website_a_editor #Implementation
+    rectangle "PG_website_a" as PG_website_a #Application
+    rectangle "DBM_website_a" as DBM_website_a #Application
+    rectangle "FM_website_a" as FM_website_a #Application
+    rectangle "FO_all" as FO_all #Application
+    rectangle "L_all" as L_all #Application
+    rectangle "CM_website_a" as CM_website_a #Application
+    rectangle "ACL_content_elements" as ACL_content_elements #Technology
+    rectangle "ACL_news" as ACL_news #Technology
+    rectangle "ACL_gallery" as ACL_gallery #Technology
+    rectangle "ACL_pages_custom" as ACL_pages_custom #Technology
+    rectangle "ACL_contact_forms" as ACL_contact_forms #Technology
+    R_website_a_editor <-- PG_website_a
+    PG_website_a -- DBM_website_a
+    DBM_website_a -- FM_website_a
+    FM_website_a -- FO_all
+    FO_all -- L_all
+    L_all -- CM_website_a
+    CM_website_a -- ACL_content_elements
+    ACL_content_elements -- ACL_news
+    ACL_news -- ACL_gallery
+    ACL_gallery -- ACL_pages_custom
+    ACL_pages_custom -- ACL_contact_forms
+}
+
+rectangle "Website B" #line.dotted {
+    rectangle "R_website_b_editor" as R_website_b_editor #Implementation
+    rectangle "PG_website_b" as PG_website_b #Application
+    rectangle "DBM_website_b" as DBM_website_b #Application
+    rectangle "FM_website_b" as FM_website_b #Application
+    rectangle "FO_all" as FO_all1 #Application
+    rectangle "L_english" as L_english #Application
+    rectangle "CM_website_b" as CM_website_b #Application
+    rectangle "ACL_content_elements" as ACL_content_elements1 #Technology
+    rectangle "ACL_survey" as ACL_survey #Technology
+    R_website_b_editor <-- PG_website_b
+    PG_website_b -- DBM_website_b
+    DBM_website_b -- FM_website_b
+    FM_website_b -- FO_all1
+    FO_all1 -- L_english
+    L_english -- CM_website_b
+    CM_website_b -- ACL_content_elements1
+    ACL_content_elements1 -- ACL_survey
+}
+
+rectangle "Website C" #line.dotted {
+    rectangle "R_website_c_editor" as R_website_c_editor #Implementation
+    rectangle "PG_website_c" as PG_website_c #Application
+    rectangle "DBM_website_c" as DBM_website_c #Application
+    rectangle "FM_website_c" as FM_website_c #Application
+    rectangle "FO_all" as FO_all2 #Application
+    rectangle "L_all" as L_all1 #Application
+    rectangle "CM_website_c" as CM_website_c #Application
+    rectangle "ACL_content_elements" as ACL_content_elements2 #Technology
+    rectangle "ACL_news" as ACL_news1 #Technology
+    R_website_c_editor <-- PG_website_c
+    PG_website_c -- DBM_website_c
+    DBM_website_c -- FM_website_c
+    FM_website_c -- FO_all2
+    FO_all2 -- L_all1
+    L_all1 -- CM_website_c
+    CM_website_c -- ACL_content_elements2
+    ACL_content_elements2 -- ACL_news1
+}
+@enduml
diff --git a/...missionsManagement/ExampleConfiguration/_backend-groups-simple-project-organized.plantuml b/...missionsManagement/ExampleConfiguration/_backend-groups-simple-project-organized.plantuml
@@ -0,0 +1,44 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "Content Editor" #line.dotted {
+  rectangle "R_content_editor" as R_content_editor #Implementation
+  rectangle "PG_website_a" as PG_website_a #Application
+  rectangle "DBM_website_a" as DBM_website_a #Application
+  rectangle "FM_website_a" as FM_website_a #Application
+  rectangle "FO_all" as FO_all #Application
+  rectangle "L_all" as L_all #Application
+  rectangle "CM_website_a" as CM_website_a #Application
+  rectangle "ACL_content_elements" as ACL_content_elements #Technology
+  rectangle "ACL_news" as ACL_news #Technology
+  rectangle "ACL_gallery" as ACL_gallery #Technology
+
+  R_content_editor <-- PG_website_a
+  PG_website_a -- DBM_website_a
+  DBM_website_a -- FM_website_a
+  FM_website_a -- FO_all
+  FO_all -- L_all
+  L_all -- CM_website_a
+  CM_website_a -- ACL_content_elements
+  ACL_content_elements -- ACL_news
+  ACL_news -- ACL_gallery
+}
+
+rectangle "Survey Manager" #line.dotted {
+  rectangle "R_survey_manager" as R_survey_manager #Implementation
+  rectangle "PG_website_a" as PG_website_a2 #Application
+  rectangle "DBM_website_a_survey" as DBM_website_a_survey #Application
+  rectangle "FM_website_a_survey" as FM_website_a_survey #Application
+  rectangle "FO_all" as FO_all2 #Application
+  rectangle "L_all" as L_all2 #Application
+  rectangle "ACL_survey" as ACL_survey #Technology
+
+  R_survey_manager <-- PG_website_a2
+  PG_website_a2 -- DBM_website_a_survey
+  DBM_website_a_survey -- FM_website_a_survey
+  FM_website_a_survey -- FO_all2
+  FO_all2 -- L_all2
+  L_all2 -- ACL_survey
+}
+@enduml
diff --git a/...ration/PermissionsManagement/ExampleConfiguration/_backend-groups-simple-project.plantuml b/...ration/PermissionsManagement/ExampleConfiguration/_backend-groups-simple-project.plantuml
@@ -0,0 +1,32 @@
+@startuml
+skinparam nodesep 10
+skinparam ranksep 20
+
+rectangle "System Groups" #line.dotted {
+  rectangle "PG_website_a" as PG_website_a #Application
+  rectangle "DBM_website_a" as DBM_website_a #Application
+  rectangle "DBM_website_a_survey" as DBM_website_a_survey #Application
+  rectangle "FM_website_a" as FM_website_a #Application
+  rectangle "FM_website_a_survey" as FM_website_a_survey #Application
+  rectangle "CM_website_a" as CM_website_a #Application
+  rectangle "FO_all" as FO_all #Application
+  rectangle "L_all" as L_all #Application
+  PG_website_a -[hidden]-> DBM_website_a
+  DBM_website_a -[hidden]-> DBM_website_a_survey
+  DBM_website_a_survey -[hidden]-> FM_website_a
+  FM_website_a -[hidden]-> FM_website_a_survey
+  FM_website_a_survey -[hidden]-> CM_website_a
+  CM_website_a -[hidden]-> FO_all
+  FO_all -[hidden]-> L_all
+}
+
+rectangle "Access Control List Groups" #line.dotted {
+  rectangle "ACL_content_elements" as ACL_content_elements #Technology
+  rectangle "ACL_news" as ACL_news #Technology
+  rectangle "ACL_gallery" as ACL_gallery #Technology
+  rectangle "ACL_survey" as ACL_survey #Technology
+  ACL_content_elements -[hidden]-> ACL_news
+  ACL_news -[hidden]-> ACL_gallery
+  ACL_gallery -[hidden]-> ACL_survey
+}
+@enduml