Improve documentation on IMS Group sync

kwin · kwin · commit 10ffd783c2c7 · 2025-11-13T11:30:51.000+01:00
diff --git a/docs/AdvancedFeatures.md b/docs/AdvancedFeatures.md
@@ -441,12 +441,7 @@ Sometimes it is also useful to create intermediate paths that do not even contai
 
 ## Update Groups in External User Management Systems
 
-Since AC Tool 3.1.0 there is support for creating/updating groups in [Adobe IMS](https://www.adobe.com/content/dam/cc/en/trust-center/ungated/whitepapers/corporate/adobe-identity-management-services-security-overview.pdf). Those are the groups which are exposed in the Adobe Admin Console and automatically used for [AEMaaCS](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/ims-support) and also [AEM 6.5 hosted by AMS](https://experienceleague.adobe.com/en/docs/experience-manager-learn/foundation/authentication/adobe-ims-authentication-technical-video-understand).
-
-To enable that feature, just set the property `externalSync` on the group to be synced in the YAML file to `true`.
-In addition an OSGi configuration for the leveraged [UMAPI](https://adobe-apiplatform.github.io/umapi-documentation/en/) needs to be provided in the configuration PID `biz.netcentric.cq.tools.actool.ims.IMSUserManagement`. This configuration should only be provided for run mode `author` to prevent the same groups from being created/updated multiple times. Also make sure you don't trigger the update too often due to [throttling of that API](https://adobe-apiplatform.github.io/umapi-documentation/en/API_introduction.html#throttling-and-error-handling).
-
-Only the group id (called name in IMS context), the description, the admins and product profiles are set for synchronized groups in IMS. Memberships are not modified and external groups are never deleted. However you can update admin users of the managed groups (this involves both adding and removing users) with the additional flag `Also update existing external groups`. This is only available for manually triggered installations from the Web Console Plugin or the Touch UI Web UI. There is right now [no way to remove product profiles](https://github.com/Netcentric/accesscontroltool/issues/800) on already existing groups.
+Since AC Tool 3.1.0 there is support for creating/updating groups in [Adobe IMS](https://www.adobe.com/content/dam/cc/en/trust-center/ungated/whitepapers/corporate/adobe-identity-management-services-security-overview.pdf). This is described in [External Group Sync via IMS](ExternalGroupSyncIms.md).
 
 ## Health Check
 
diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -104,7 +104,7 @@ members | List of groups that are member of this group. May be provided as yaml
 migrateFrom | A group name assigned member users are taken over from. This is not supported for external user management. | optional
 virtual | If true, the group is *not* created in repository but only its permissions and isMemberOf relationships are made effective to other groups using the virtual group in isMemberOf. Flattens the effective group tree of users at runtime, but enlarges ACLs as set on path (instead of the virtual group, all referencing groups are listed in a particular path's ACL used by the virtual group). Useful for functionality fragments. False by default. Since v2.1.0 | optional
 unmanaged* Properties | Only use sparsely and with care, see [Advanced Features](AdvancedFeatures.md)   | optional
-externalSync | Boolean flag determining whether the group should also be created or updated in a configured external user management system. For further details refer to [Update Groups in External User Management Systems](AdvancedFeatures.md#update-groups-in-external-user-management-systems). Since v3.1.0. | optional
+externalSync | Boolean flag determining whether the group should also be created or updated in a configured external user management system. For further details refer to [External Group Sync via IMS](ExternalGroupSyncIms.md). Since v3.1.0. | optional
 
 Example:
 
diff --git a/docs/ExternalGroupSyncIms.md b/docs/ExternalGroupSyncIms.md
@@ -0,0 +1,50 @@
+# External Group Sync (with IMS)
+
+Since AC Tool 3.1.0 there is support for creating/updating groups in [Adobe IMS](https://www.adobe.com/content/dam/cc/en/trust-center/ungated/whitepapers/corporate/adobe-identity-management-services-security-overview.pdf). Those are the groups which are exposed in the Adobe Admin Console and automatically used for [AEMaaCS](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/security/ims-support) and also [AEM 6.5 hosted by AMS](https://experienceleague.adobe.com/en/docs/experience-manager-learn/foundation/authentication/adobe-ims-authentication-technical-video-understand).
+
+
+## Architecture
+
+Here is the different actors involved in IMS Group sync
+
+
+```mermaid
+---
+title: IMS Group Sync
+---
+sequenceDiagram
+box AEM
+    participant ACTool
+    participant AEM Groups
+    participant AEM Users
+end
+box Adobe IMS
+    participant IMS OIDC Login
+    participant IMS Users
+    participant IMS Groups
+end
+    ACTool->>+IMS Groups: Create/Update ('externalSync')
+    ACTool->>+AEM Groups: Create/Update groups synchronized with IMS ('externalId')
+    Note over ACTool: 1. Triggered via Installation
+    IMS Users ->> IMS Groups: Grant access via group membership
+    Note over IMS Groups: 2. Authorization via Admin Console
+    
+    IMS OIDC Login->>AEM Users: Create/Update
+    IMS OIDC Login->>AEM Groups: Add members
+    Note over IMS OIDC Login: 3.Authentication
+```
+
+## Configuration
+
+To enable that feature, just set the property `externalSync` on the group to be synced in the YAML file to `true`. In order to assign ACLs to those groups make sure that `externalId` is set correctly (otherwise the group on AEM side will not be used for IMS users).
+In addition an OSGi configuration for the leveraged [UMAPI](https://adobe-apiplatform.github.io/umapi-documentation/en/) needs to be provided in the configuration PID `biz.netcentric.cq.tools.actool.ims.IMSUserManagement`. This configuration should only be provided for run mode `author` to prevent the same groups from being created/updated multiple times. Also make sure you don't trigger the update too often due to [throttling of that API](https://adobe-apiplatform.github.io/umapi-documentation/en/API_introduction.html#throttling-and-error-handling).
+
+## What is synchronized?
+
+Only the 
+- group id (called name in IMS context), 
+- the description
+- the admins (set via OSGi configuration)
+- and product profiles (set via OSGi configuration)
+
+are set for synchronized groups in IMS. Memberships are not modified and external groups are never deleted. However you can update admin users of the managed groups (this involves both adding and removing users) with the additional flag `Also update existing external groups`. This is only available for manually triggered installations from the Web Console Plugin or the Touch UI Web UI. There is right now [no way to remove product profiles](https://github.com/Netcentric/accesscontroltool/issues/800) on already existing groups.
