The User Sync tool is a command-line utility that moves user and group information from your organization’s enterprise directory system (such as an Active Directory or other LDAP systems) to your organization’s directory in the Adobe Admin Console. Each time you run the User Sync tool, it looks for differences between the user and group information in the two systems and updates the Adobe directory to match the information in your directory.
This document provides step-by-step instructions to interface an Active Directory system with the Adobe Admin Console. This is one of the most popular combinations that our customers use in the K-12 and SMB segments. The User Sync tool is flexible and can be used to interface with most LDAP and directory systems. If you're using a directory system other than Active Directory, the instructions in this document do not apply directly; modify as required. For more information, see the Setup and Success Guide.
You need the following information about your LDAP system. If you do not have this information, contact your IT administrator.
- Domain controller name (or its IP, if fixed) and port.
- User name and password to a service account that the tool can use to extract users from your LDAP (read-only access).
- Base DN, which is the point from where the server searches for users; it should be wide enough to allow the discovery of all users and groups requiring to be synced.
- Group names that are a part of the synchronization.
- The best suited LDAP attribute for mail/username for all users needing to be created in Admin Console.
- (Optional) You might also require a custom LDAP query that selects the set of users to be synced with Adobe if the default filters don't cover the requirements.
The key pair is used to sign a JWT and verify its legitimacy in obtaining the access_token process. To assist you on this process, contact your security team, if necessary.
- Public certificate can be signed by your own CA (raise a CSR if necessary); self signed ones are accepted too
- Private key should be RSA: 2048 bits at min
- The public certificate should have a .crt extension
- Sign using SHA-256
- Public key validity: three years recommended but your internal security policy will dictate
Create a self-signed certificate
For testing and setting up, you can also use a self-signed certificate using openssl. For Mac OS/Linux, openssl might come by default. For Windows, add openssl support separately (for example, Cygwin)
To create a self-signed certificate follow these steps:
If you plan to install User Sync on your machine, ensure that it meets the following requirements:
- Has access to the Internet, and your directory service such as LDAP or AD.
- Is protected and secure (your administrative credentials are stored or accessed there).
- Stays up, is reliable, and has a backup and recovery capability.
- Can send emails so User Sync can send reports to administrators.
- If it is a Windows machine, it has a 64-bit processor.
Otherwise, work with your IT department to identify such a server and get access to it.
Sign in to the Adobe I/O Console, select your organization from the drop-down list, and click New Integration.
Access GitHub and locate the Latest release tag.
Inside this release, find and expand the Assets. Then, locate and download:
- The examples.zip file
- The .zip of the User Sync Tool in the list that matches your OS type and Python version
The name of the archive contains the OS type it works on and also with what Python version it was built. For example, user-sync-vX.Y-win64-py368.zip is a Windows release, built with Python 3.6.8 (64 bit).
If you don't have a Python version installed on the system, try to match/install the one the tool was built with.
Verify the rest of the uncommented settings and what LDAP attributes they point to. Change them according to your needs.
Some deployments have username-based login set up (Username field in Admin Console for a given user is not an email type of value).
In this case, enable the following line too (remove the # char):
Replace the sAMAccountName with the right attribute if it's not the one you need to use.
A country code is required for Federated IDs and recommended for Enterprise IDs. If not supplied for Enterprise IDs, the users are prompted to choose a country when they first log in.
This section defines what groups from LDAP should have a corresponding user-group or PLC in Admin Console.
The target here is to give the tool a source of groups/users so that it can match the same members in Admin Console side groups/PLCs.
For each directory group that must map to an Adobe Product Profile or user group, add an entry inside the groups section. For example:
groups: - directory_group: LDAP_group_name_goes_here adobe_groups: - Adobe_group_name_goes_here - directory_group: LDAP_group_name_goes_here adobe_groups: - Adobe_group_name_goes_here
Group mapping can be done using Adobe User Groups or Product Profiles, not to Product names. And, you can map one directory group to more than one Adobe User Groups or Product Profiles.
To prevent accidental account removal if there is a misconfiguration or another problem, you can decide a limit of maximum number of account removals you'd expect in your daily sync.
If you expect the number of account removals to be more than the set max_adobe_only_users value between User Sync runs, raise the value to cover all account removals.
If the number of accounts to be removed is more than the max_adobe_only_users value, the tool would not process any account removal. A critical entry appears in the log that announces reaching that limit.
This limit does not impact the create actions.
There are situations where some accounts must be excluded from the synchronization. This can be achieved by editing the user-sync-config.yml file.
The tool offers three exclude features: by identity type, by group name and by regular expression.
Any account found in Admin Console that fits in at least one of the mentioned criteria is protected from remove actions (from group, from Org).
It's a good practice to have AdobeIDs for System Administrators in Admin Console and exclude them via exclude by exclude_identity_types: adobeID
Here is a sample:
User Sync produces log entries that are printed to standard output and also written to a log file. The logging set of configuration settings control details of where and how much log information is output.
Alternatively, if you have a Windows server, you can use the User Sync Tool Configuration wizard to configure User Sync.
The User Sync Tool Configuration wizard is a GUI tool that helps you easily configure the User Sync tool with User Management API (Adobe.io), Enterprise Directory (LDAP), and sync settings. It provides context-based help and links to User Sync tool documentation. For more information, see Adobe User Sync Tool Configuration wizard.
Now that the User Sync tool is set up on your server or machine, you can check if it works as expected. To troubleshoot the common issues while running the User Sync Tool, see tips to resolve common errors.
In test mode, run a sync limited to the mapped groups named in the config file, excluding the existing Adobe side accounts.
python user-sync.pex -t --users mapped --process-groups --adobe-only-user-action exclude
The command above syncs only the users in the mapped group specified in user-sync-config.yml. If the users don't exist in the Admin Console, it results in an attempt to create the users and add them to any groups that are mapped from their directory groups.
Running user-sync in test mode (-t) only attempts to create the user and not actually do it. The --adobe-only-user-action exclude option prevents removal of any existing user account in the Adobe organization.
Although the invocation_defaults sets the default arguments the tool runs with, you can override them by mentioning them in command line. In test mode, run a sync limited to the mapped groups named in the config file, removing the extra accounts found on Adobe side and not found in the LDAP extraction.
python user-sync.pex -t --users mapped --process-groups --adobe-only-user-action remove
extract users from LDAP that are results of both all_user_filter and member of the provided directory_group names in the config file.
add/remove users to/from the Adobe side user-groups or PLCs, based on account being or not member of the LDAP mapped groups.
any account found on Adobe side is removed from Users menu and entitlements stripped off if not found in the LDAP extraction and not being excluded from sync.
- The provided command lines are just examples and might not cover the entirety of use-cases.
- Initial sync can take from seconds to hours depending on the number of accounts to sync. Roughly 250 users get created every 1.5-2 minutes (including time-out).
- The UMAPI timeout warning code 429 messages are expected. The tool handles the retry mechanism.
User Sync can be run manually, or you can set up automation where it runs once to a few times per day automatically.
If you have a log analysis and alerting system available, arrange for the log from User Sync to be sent to the log analysis system. And, set up alerts for any Error or Critical messages that appear in the log.
To pull out relevant log entries for a summary, create a batch file in the user_sync_tool folder with the invocation of user-sync piped to a scan. For example, create a file run_sync.bat with contents like:
cd path/to/user-sync-folder python user-sync.pex --users file example.users-file.csv --process-groups | findstr /I "==== ----- WARNING ERROR CRITICAL Number" > temp.file.txt rem email the contents of temp.file.txt to the user sync administration your-mail-tool –send file temp.file.txt