User Synchronization
- Topics:
- Administering
CREATED FOR:
- Admin
Introduction
When the deployment is a publish farm, members need to be able to log in and see their data on any publish node.
Users and user groups (user data) created in the publish environment are not needed in the author environment.
Most user data created in the author environment is intended to remain in the author environment and not be copied to publish instances.
Registration and modifications made on one publish instance need to be synchronized with other publish instances in order for them to have access to the same user data.
As of AEM 6.1, when user synchronization is enabled, user data is automatically synchronized across the publish instances in the farm and are not created on author.
Sling Distribution
The user data, along with their ACLs, are stored in the Oak Core, the layer below Oak JCR, and are accessed using the Oak API. With infrequent updates, it is reasonable for user data to be synchronized with other publish instances using Sling Content Distribution (Sling distribution).
The benefits of user sync using Sling distribution, compared to traditional replication are :
-
users, user profiles and user groups created on publish are not created on author
-
Sling distribution sets properties in jcr events, making it possible to act within publish-side event listeners without concern for infinite replication loops
-
Sling distribution only sends user data to non-originating publish instances, eliminating unnecessary traffic
-
ACLs set in the user node are included in the sychronization
Enable User Sync
disabled
.User sync relies on the author environment to manage the user data distributions, even though the user data is not created on author. Much, but not all, of the configuration takes place in the author environment and each step clearly identifies whether it is to be performed on author or publish.
Following are the steps necessary to enable user synchronization, followed by a Troubleshooting section:
Prerequisites
-
If users and user groups have already been created on one publisher, it is recommended to manually sync the user data to all publishers prior to configuring and enabling user sync.
Once user sync is enabled, only newly created users and groups are syncrhonized.
-
Ensure the latest code has been installed:
1. Apache Sling Distribution Agent - Sync Agents Factory
Enable user sync
-
on author
-
sign in with administrator privileges
-
access the Web Console
- for example, http://localhost:4502/system/console/configMgr
-
locate
Apache Sling Distribution Agent - Sync Agents Factory
-
select the existing configuration to open for edit (pencil icon)
Verify
name
:socialpubsync
-
select the
Enabled
checkbox -
select
Save
-
-
2. Create Authorized User
Configure permissions
This authorized user will be used in step 3 to configure Sling distribution on author.
-
on each publish instance
-
sign in with administrator privileges
-
access the Security Console
- for example, http://localhost:4503/useradmin
-
create a new user
- for example,
usersync-admin
- for example,
-
add this user to the
administrators
user group -
add ACL for this user to /home
Allow jcr:all
with restrictionrep:glob=*/activities/*
-
- The default user assigned is
admin
. - Do not use
*communities-user-admin *user*.*
How to Add ACL
-
access CRXDE Lite
- for example, http://localhost:4503/crx/de
-
select
/home
node -
in right pane, select the
Access Control
tab -
select the
+
button to add an ACL entry- Principal: search for user created for user sync
- Type:
Allow
- Privileges:
jcr:all
- Restrictions rep
*/activities/*
- select OK
-
select Save All
See also
- Access Right Management
- Troubleshooting section Modify Operation Exception During Response Processing.
3. Adobe Granite Distribution - Encrypted Password Transport Secret Provider
Configure permissions
Once an authorized user, a member of the **administrators
**user group, has been created on all publish instances, that authorized user must be identified on author as having permission to sync user data from author to publish.
-
on author
-
sign in with administrator privileges
-
access the Web Console
- for example, http://localhost:4502/system/console/configMgr
-
locate
com.adobe.granite.distribution.core.impl.CryptoDistributionTransportSecretProvider.name
-
select the existing configuration to open for edit (pencil icon)
Verify
property name
:socialpubsync-publishUser
-
set the username and password to the authorized user created on publish in step 2
- for example,
usersync-admin
- for example,
-
4. Apache Sling Distribution Agent - Queue Agents Factory
Enable user sync
-
on publish :
-
sign in with administrator privileges
-
access the Web Console
- for example, http://localhost:4503/system/console/configMgr
-
locate
Apache Sling Distribution Agent - Queue Agents Factory
-
select the existing configuration to open for edit (pencil icon)
Verify
Name
:socialpubsync-reverse
-
select the
Enabled
checkbox -
select
Save
-
-
repeat for each publish instance
-
5. Adobe Granite Distribution - Diff Observer Factory
Enable group sync
-
on each publish instance :
-
sign in with administrator privileges
-
access the Web Console
- for example, http://localhost:4503/system/console/configMgr
-
locate
Adobe Granite Distribution - Diff Observer Factory
-
select the existing configuration to open for edit (pencil icon)
Verify
agent name
:socialpubsync-reverse
-
select the
Enabled
checkbox -
select
Save
-
-
6. Apache Sling Distribution Trigger - Scheduled Triggers Factory
(Optional) modify polling interval
By default, author will poll for changes every 30 seconds. To alter this interval :
-
on author
-
sign in with administrator privileges
-
access the Web Console
- for example, http://localhost:4502/system/console/configMgr
-
locate
Apache Sling Distribution Trigger - Scheduled Triggers Factory
-
select the existing configuration to open for edit (pencil icon)
- Verify
Name
:socialpubsync-scheduled-trigger
- Verify
-
set the
Interval in Seconds
to the desired interval -
select
Save
-
-
Configure for Multiple Publish Instances
The default configuration is for a single publish instance. As the reason for enabling user sync is to synchronize multiple publish instances, such as for a publish farm, the additional publish instances will need to be added to the Sync Agents Factory.
7. Apache Sling Distribution Agent - Sync Agents Factory
Add Publish Instances :
-
on author
-
sign in with administrator privileges
-
access the Web Console
- for example, http://localhost:4502/system/console/configMgr
-
locate
Apache Sling Distribution Agent - Sync Agents Factory
-
select the existing configuration to open for edit (pencil icon)
Verify
Name
:socialpubsync
-
-
-
Exporter Endpoints
There should be an exporter endpoint for each publisher. For example, if there are 2 publishers, localhost:4503 and 4504, there should be 2 entries:- http://localhost:4503/libs/sling/distribution/services/exporters/socialpubsync-reverse
- http://localhost:4504/libs/sling/distribution/services/exporters/socialpubsync-reverse
-
Importer Endpoints
There should be an importer endpoint for each publisher. For example, if there are 2 publishers, localhost:4503 and 4504, there should be 2 entries:- http://localhost:4503/libs/sling/distribution/services/importers/socialpubsync
- http://localhost:4504/libs/sling/distribution/services/importers/socialpubsync
-
select
Save
8. AEM Communities User Sync Listener
(Optional) Sync additional JCR nodes
If there is custom data that is desired to be synchronized across multiple publish instances, then:
-
on each publish instance:
-
sign in with administrator privileges
-
access the Web Console
- for example, http://localhost:4503/system/console/configMgr
-
locate
AEM Communities User Sync Listener
-
select the existing configuration to open for edit (pencil icon)
Verify
Name
:socialpubsync-scheduled-trigger
-
-
Node Types
This is the list of node types that will synchronize. Any node type other than sling:Folder needs to be listed here (sling:folder is handled separately).
Default list of node types to synchronize:
- rep:User
- nt:unstructured
- nt:resource
-
Ignorable Properties
This is the list of properties that will be ignored if any change is detected. Changes to these properties might get synchronized as a side effect of other changes (since synchronization is always at the node level), but changes to these properties will not by themselves trigger synchronization.
Default property to ignore:
- cq:lastModified
-
Ignorable Nodes
Subpaths that will be entirely ignored during synchronization. Nothing under these subpaths will be synchronized at any time.
Default nodes to ignore:
- .tokens
- system
-
Distributed Folders
Most sling:Folders are ignored because synchronization is not necessary. The few exceptions are listed here.
Default folders to synchronize
- segments/scoring
- social/relationships
- activities
9. Unique Sling ID
If the Sling ID is the same for multiple publish instances in a publish farm, then user groups will not be synchronized.
To validate that all Sling ID values differ, on each publish instance :
- browse to
http://<host>:<port>/system/console/status-slingsettings
- check the value of Sling ID
If the Sling ID of a publish instance matches the Sling ID of any other publish instance, then:
-
stop one of the publish instances that has a matching Sling ID
-
in the crx-quickstart/launchpad/felix directory
-
search for and delete the file named sling.id.file
-
for example, on a Linux system:
rm -i $(find . -type f -name sling.id.file)
-
for example, on a Windows system:
use windows explorer and search for *sling.id.file*
-
-
-
start the publish instance
- on startup it will be assigned a new Sling ID
-
validate that the Sling ID is now unique
Repeat these steps until all publish instances have an unique Sling ID.
Vault Package Builder Factory
In order for updates to sync properly, it is necessary to modify the vault package builder for user sync :
-
on each AEM publish instance
-
access the Web Console
- for example, http://localhost:4503/system/console/configMgr
-
locate the
Apache Sling Distribution Packaging - Vault Package Builder Factor
Builder name: socialpubsync-vlt
-
select the edit icon
-
add two
Package Filters
:/home/users|-.*/.tokens
/home/users|-.*/rep:cache
-
policy handling :
-
to overwrite existing rep:policy nodes with new ones, add a third Package Filter :
/home/users|+.*/rep:policy
-
to prevent policies from being distributed, set
Acl Handling :
IGNORE
-
What Happens When …
User Self-Registers or Edits Profile on Publish
By design, users and profiles created in the publish environment (self-registration) do not appear in the author environment.
When the topology is a publish farm and user sync has been correctly configured, the *user *and user profile is synchronized across the publish farm using Sling distribution.
Users or User Groups are Created Using Security Console
By design, user data created in the publish environment does not appear in the author environment and vice versa.
When the User Administration and Security console is used to add new users in the publish environment, user sync will synchronize the new users and their group membership to other publish instances, if necessary. User sync will also synchronize user groups created through the security console.
Troubleshooting
How to Take User Sync Offline
To take user sync offine, in order to remove a publisher or manually sync data, the distribution queue must be empty and quiet.
To check the state of the distribution queue:
-
on author:
-
using CRXDE Lite
-
look for entries in
/var/sling/distribution/packages
- folder nodes named with the pattern
distrpackage_*
- folder nodes named with the pattern
-
-
using Package Manager
-
look for pending packages (not yet installed)
- named with the pattern
socialpubsync-vlt*
- created by
communities-user-admin
- named with the pattern
-
-
When the distribution queue is empty, disable user sync :
-
on author
- *uncheck *the
Enabled
checkbox for Apache Sling Distribution Agent - Sync Agents Factory
- *uncheck *the
Once tasks are completed, to re-enable user sync :
-
on author
- check the
Enabled
checkbox for Apache Sling Distribution Agent - Sync Agents Factory
- check the
User Sync Diagnostics
User Sync Diagnostics is a tool that checks the configuration and attempts to identify any problems.
On author, simply navigate from the main console through Tools, Operations, Diagnosis, User Sync Diagnostics.
Simply entering the User Sync Diagnostics console will display the results.
This is what is displayed when User Synchronization has not been enabled :
How To Run Diagnostics for Publishers
When the diagnoistic is run from the author environment, the pass/fail results will include an [INFO] section displaying the list of configured publish instances for confirmation.
Included in the list is an URL for each publish instance that will run the diagnostics for that instance. The url param syncUser
is appended to the diagnostics URL with its value set to the authorized sync user created in Step 2.
Note : before launching the URL, the authorized sync user must already be signed into that publish instance.
Configuration Improperly Added
When user sync fails to work, the most common problem is that additional configurations were added. Instead, the *existing *default configuration should have been edited.
Following are views of how the edited, default configurations should appear in the Web Console. If more than the one instance appears, the added configuration should be removed.
(author) One Apache Sling Distribution Agent - Sync Agents Factory
(author) One Adobe Granite Distribution - Encrypted Password Transport Secret Provider
(publish) One Apache Sling Distribution Agent - Queue Agents Factory
(publish) One Adobe Granite Distribution - Diff Observer Factory
(author) One Apache Sling Distribution Trigger - Scheduled Triggers Factory
Modify Operation Exception During Response Processing
If the following is visible in the log :
org.apache.sling.servlets.post.impl.operations.ModifyOperation Exception during response processing.
java.lang.IllegalStateException: This tree does not exist
Then verify that the section 2. Create Authorized User was properly followed.
This section describes creating an authorized user, who exists on all publish instances, and identifying them in the ‘Secret Provider’ OSGi config on author. By default, the user is admin
.
The authorized user should be made a member of the administrators
user group and permissions for that group should not be altered.
The authorized user should explicitly have the following privileges and restriction on all publish instances :
path | jcr:all | rep:glob |
---|---|---|
/home | X | */activities/* |
/home/users | X | */activities/* |
/home/groups | X | */activities/* |
As a member of the administrators
group, the authorized user should have the following privileges on all publish instances :
path | jcr:all | jcr:read | rep:write |
---|---|---|---|
/etc/packages/sling/distribution | X | ||
/libs/sling/distribution | X | ||
/var | X | ||
/var/eventing | X | X | |
/var/sling/distribution | X | X |
User Group Sync Failed
If the Sling ID matches between two or more publish instances then user group sync will fail.
See section 9. Unique Sling ID
Manually Syncing Users and User Groups
-
on publisher on which users and user groups exist :
-
create a package of
/home
-
when editing the package
- Filters tab : Add Filter : Root path:
/home
- Advanced tab : AC Handling :
Overwrite
- Filters tab : Add Filter : Root path:
-
-
on other publish instances :
To configure or enable user sync, go to step 1: Apache Sling Distribution Agent - Sync Agents Factory
When a Publisher Becomes Unavailable
When a publish instance becomes unavailable, it should not be removed if it will be back online in the future. Changes will queue up for the publisher, and once it is back online, the changes will be processed.
If the publish instance will never be back online, if it is offline permanently, then it must be removed because the queue buildup will result in noticeable disk space usage in the author environment.
When a publisher is down, the author log will have exceptions similar to :
28.01.2016 15:57:48.475 ERROR
[pool-12-thread-34-org_apache_sling_distribution_queue_socialpubsync_endpoint1
(org/apache/sling/distribution/queue/socialpubsync/endpoint1)]
org.apache.sling.distribution.agent.impl.SimpleDistributionAgent [agent][socialpubsync] could not deliver package distrpackage_1454014575838_a2b45ec8-0400-42f3-bed8-ae09b66381cb
org.apache.sling.distribution.packaging.DistributionPackageImportException: failed in importing package ...
How To Remove a Publisher
To remove a publisher from the Apache Sling Distribution Agent - Sync Agents Factory, the distribution queue must be empty and quiet.
-
on author :
-
follow step 7 to remove the publisher from both server lists :
Exporter Endpoints
Importer Endpoints
-
re-enable user sync
- check the
Enabled
checkbox for Apache Sling Distribution Agent - Sync Agents Factory
- check the
Experience Manager
- Administering User Guide overview
- Sites Features
- Website Administration
- Reusing Content: Multi Site Manager and Live Copy
- Live Copy Overview Console
- Configuring Live Copy Synchronization
- Creating and Synchronizing Live Copies
- MSM Rollout Conflicts
- MSM Best Practices
- Translating Content for Multilingual Sites
- Managing Translation Projects
- Identifying Content to Translate
- Preparing Content for Translation
- Creating a Language Root Using the Classic UI
- Connecting to Microsoft Translator
- Configuring the Translation Integration Framework
- Language Copy Wizard
- Translation Enhancements
- Translation Best Practices
- Configurations and the Configuration Browser
- AEM FAQs
- Operations
- Dashboards
- Operations Dashboard
- Backup and Restore
- Data Store Garbage Collection
- Monitoring Server Resources Using the JMX Console
- Working with Logs
- Configure the Rich Text Editor
- Configure the Video component
- The Bulk Editor
- Configuring Email Notification
- Configuring RTE for Producing Accessible Sites
- The Link Checker
- Troubleshooting AEM
- Audit Log Maintenance in AEM 6
- Editor
- Managing Access to Workflows
- Using cURL with AEM
- Configuring Undo for Page Editing
- Proxy Server Tool (proxy.jar)
- Configuring for AEM Apps
- Administering Workflows
- Configuring Search Forms
- Tools Consoles
- Reporting
- Administering Workflow Instances
- Configuring Layout Container and Layout Mode
- Enabling Access to Classic UI
- Starting Workflows
- Configure the Rich Text Editor plug-ins
- Admin Consoles
- Security
- User Administration and Security
- User, Group and Access Rights Administration
- Security Checklist
- OWASP Top 10
- Running AEM in Production Ready Mode
- Identity Management
- Adobe IMS Authentication and Admin Console Support for AEM Managed Services
- Creating a Closed User Group
- Mitigating serialization issues in AEM
- User Synchronization
- Encapsulated Token Support
- Single Sign On
- How to Audit User Management Operations in AEM
- SSL By Default
- SAML 2.0 Authentication Handler
- Closed User Groups in AEM
- Granite Operations - User and Group Administration
- Enabling CRXDE Lite in AEM
- Configuring LDAP with AEM 6
- Configure the Admin Password on Installation
- Service Users in AEM
- Encryption Support for Configuration Properties
- Handling GDPR Requests for the AEM Foundation
- Content Disposition Filter
- Personalization
- eCommerce
- Integration
- Integrating with Third-Party Services
- Integrating with Salesforce
- Integrating with Adobe Target
- Integrating with Adobe Analytics
- Connecting to Adobe Analytics and Creating Frameworks
- Configuring Link Tracking for Adobe Analytics
- Mapping Component Data with Adobe Analytics Properties
- Configuring Video Tracking for Adobe Analytics
- HTTP2 Delivery of Content FAQ
- Troubleshooting your Adobe Campaign Integration
- SharePoint Connector Licenses, Copyright Notices, and Disclaimers
- SharePoint Connector
- DHTML Viewer End-of-Life FAQs
- Integrating with Adobe Campaign Classic
- Related Community Articles
- Integrating with Adobe Campaign Standard
- Flash Viewers End-of-Life Notice
- Integrating with Adobe Creative Cloud
- Integrating with Adobe Dynamic Tag Management
- Opting Into Adobe Analytics and Adobe Target
- AEM Portals and Portlets
- Integrating with Dynamic Media Classic
- Troubleshooting Integration Issues
- Integrating with BrightEdge Content Optimizer
- Best Practices for Email Templates
- Catalog Producer
- Integrating with Silverpop Engage
- Integrating with Adobe Campaign
- Integrating with ExactTarget
- Analytics with External Providers
- Integrating with the Adobe Marketing Cloud
- Manually Configuring the Integration with Adobe Target
- Prerequisites for Integrating with Adobe Target
- Adobe Classifications
- Solutions Integration
- Target Integration with Experience Fragments
- Best Practices
- Content Management