Table of contents
- Config File Setup
User Sync Tool behavior is governed by a set of configuration files.
These files are typically placed in the same directory as the User Sync Tool executable.
Although this overview covers the configuration files for Sign Sync, this page focuses on UMAPI sync. See Sign Sync for details around configuring Sign Sync.
After a brief overview of the configuration files used by the User Sync Tool and some general notes, this page focuses on the configuration options used in
These configuration files are required to synchronize users to the Admin Console.
user-sync-config.yml- Main config file for Admin Console Sync
connector-umapi.yml- Defines connection to the User Management API. Stores credentials (or keychain references) and defines advanced connection options. If you plan to synchronize to multiple UMAPI targets, then each connection is configured in a different UMAPI connector config file.
These configuration files are required to synchronize users to Adobe Acrobat Sign.
sign-sync-config.yml- Main config file for Sign Sync
connector-sign.yml- Defines a connection to a Sign account (using the Sign API). Multiple connections are supported (each in their own connector config file).
These configuration files define connections to various identity sources. They can be used with both UMAPI sync and Sign Sync. They are only required if the connector is enabled. The exception - when using UMAPI sync,
connector-csv.yml is totally optional assuming the CSV uses the standard headers and encoding (
utf-8). The CSV connector is required when using Sign Sync.
connector-ldap.yml- Defines connection to an LDAP system such as Active Directory
connector-okta.yml- Defines connection to an Okta tenant (using the Okta API)
connector-adobe-console.yml- Defines a connection to the UMAPI for treating an Admin Console organization as an identity source. Useful in cases when synchronizing to a console-linked Sign account, or when syncing to an Admin Console org with a trusted Azure AD-synced directory
connector-csv.yml- Defines header columns and encoding of CSV input file
The extension config (
extension-config.yml) can be set up for use with UMAPI sync to get more control over how syncs are executed. See advanced configuration for details.
Example configuration files can be obtained in several ways:
- In the
examplesfolder of the code repository
- The example bundles (
user-sync-examples.tar.gz) on any release page
./user-sync example-configfrom the command line (recommended)
Configurations files are in YAML format and use the
yml suffix. When editing YAML, remember some important rules:
Indentation governs scope and heirarchy (as opposed to a system like JSON which uses curly braces)
Keys and values are delimited with a single colon (
:) followed by a space character
some_key: A Value
A dash (
-) denotes a list item
# example with one item adobe_groups: - Photoshop Users # example with multiple items adobe_groups: - Photoshop Users - Lightroom Users - Illustrator Users
Tip: use a developer-friendly text editor such as Notepad++ for maximum ease-of-use.
If you’re not using Windows, we recommend an editor with these features.
- Line numbers
- YAML syntax highlighting
- Smart indentation
- Ability to set line endings and file encoding
- Ability to show special characters (tabs, line endings, etc)
A basic example:
- directory_group: adobe-all-apps
- All Apps
adobe_users config key contains all of the options pertinent to Adobe-side sync management.
- Define Admin Console/User Management API (UMAPI) sync targets
- Define rules to exclude certain users from sync
- Exclude certain identity types
- Exclude certain groups
- Exclude specific users by email address regular expression
Note that the exclusion rules defined here only apply to the Adobe-side workflow. That is to say these filters are applied to user information queried from the Admin Console using the UMAPI.
This option defines a list of identity types to exclude. It generally should just be set to
adobeID since it isn’t common for a console to have both
enterpriseID directories and
adobeID users should generally always be excluded as a best practice.
Here the config defines a list of user groups or product profiles to exclude from sync.
This can include any user group, product profile, or admin group you wish to exclude from sync.
At minimum, it should include the special group name
_org_admin which denotes users with system admin privileges.
Note that you may have other users you might wish to exclude here - developer accounts, support admins, etc. They should also be excluded here if needed.
Exclude individual users by email address or a list of users with a regular expression.
adobe_users.connectors defines one or more connections to the User Management API (UMAPI).
Each connection should at minimum contain a reference to the UMAPI connector config (e.g.
connector-umapi.yml). Secondary targets also require an identifier field.
To configure a single target,
connectors should be set to a single configuration file reference. This should point to your main UMAPI config (e.g.
umapi key tells the sync tool that the UMAPI connector is in use.
To target multiple console organizations, the
umapi key is specified as a list instead of a plain string.
Each target must have its own connector configuration file as well as its own set of UMAPI credentials.
The User Sync Tool expects all target consoles to be related via directory trust.
- The main target should own the directories and domains associated with UST-managed users
- Other targets should be trustees of the main target
This primary-secondary structure is represented in the
- org2: connector-umapi-org2.yml
umapi key, the config file for the primary (identity-owning) target is specified as a plain string. Each secondary target is specified as a key-value pair with the key being a unique identifier for the target. This ID is used for several key purposes:
- Targeting org-specific groups in the group mapping
- Distinguishing between targets in log messages
- Identifying different targets internally
--update-user-info/update_user_info is enabled (see runtime config), the user attributes updated for a given user can be controlled with
# - username
By default, the
username is disabled by default.
If sync is run with
update_user_info enabled and any changes are detected to a disabled attribute for a given user, the Sync Tool logs a warning:
2023-07-12 13:32:55 54531 WARNING processor - 'username' has changed for user
> but that attribute isn't configured for updating
[line continuations added for clarity]
Every option under the
directory_users key pertains to managing general identity source behavior. This includes:
- Defining the connector type
- Linking the connector config file
- Defining default country code and identity type
- Defining how directory groups map to Adobe groups
The country code is a mandatory attribute for every Adobe user. It governs the location in which a user’s data is stored, among other things.
federatedID users, the country code must be specified on user creation. On
adobeID users, it can be set to
UD to leave the country undefined. In this case, the user will select their own country when they log in for the first time.
UD (which is not a valid country code), the country code must be a valid ISO-3166-1 alpha-2 code.
default_country_code defines the code to use when the identity source does not specify a country code for a given user. It is only set for a given user whose “country” field is empty. If a user’s country is set to anything, even a country in a format not accepted by the UMAPI, the Sync Tool will attempt to set it for a user. This operation will only succeed if the country code is in the expected format.
The extension config can be used to normalize country codes that aren’t in the expected format.
connectors key under
directory_users is where identity source connectors are defined. This is done by setting the connector type as the key and the configuration filename as the value.
Multiple connectors can be defined here (though only one can be enabled at any given time).
Once an identity connector is configured, it must be enabled to be used. The connector can be enabled in the invocation defaults settings or command-line options.
The default identity type of new users is controlled by the
user_identity_type option. This can be overridden by identity options that may be available via identity source connectors.
Valid options are
Here is some additional information about Adobe’s different identity types.
Note: in the UMAPI, Business IDs are represented by their underlying linked account types. In other words, there is no
groups option defines a mapping that describes rules for how identity source groups should govern Adobe groups.
groupsconsists of a list of at least one mapping object
- Each mapping object has two keys
directory_group- Name of directory group to map
adobe_groups- List of zero or more Adobe groups to map
- directory_group: adobe-acrobat
- "Default Acrobat Pro DC configuration"
- directory_group: adobe-creative
- "Default Photoshop CC - 100 GB configuration"
- "Default All Apps plan - 100 GB configuration"
In this example, any user queried by the identity source belonging to the source group
adobe-acrobat is assigned the Adobe group
Default Acrobat Pro DC configuration.
Any user beloning to the directory group
adobe-creative is assigned both of these Adobe groups:
Default Photoshop CC - 100 GB configuration
Default All Apps plan - 100 GB configuration
Users assigned to both
adobe-creative will be assigned all three Adobe groups in the mapping.
The User Management API doesn’t distinguish between product profile group names and user group names. They are treated identically when assigning group membership to a user.
The only way the use of user groups is different is if automatic group creation is enabled.
Admin roles can be assigned to users by the User Sync tool using special group names and prefixes. Using these special naming conventions, admin roles can be assigned like any normal product profile or user group.
|Name or Prefix
|User Group or Profile Admin
* The User Management API does not currently support the assignment of the System Admin role. This means that System Admins cannnot be assigned in the group mapping. This role can however be used in the
Notes about the Product Admin role:
- It may be necessary to manually assign a user as admin to a product before syncing users as product admins.
- The product admin role group name is case-sensitive.
- It is often necessary to assign users to at least one profile on the same product as the admin role.
See the UMAPI Docs for more details.
Configures dynamic group mappings based on regular expression rules. See advanced config for more information.
group_sync_options controls the synchronization of user groups. The only supported option at the moment is
auto_create which will automatically create user groups targetted by the group mapping. See advanced config for more information.
User offboarding behavior (i.e. the Adobe-only user action) can be a destructive operation. Care should be taken with how your user sync workflow is configured.
In particular, the following
--adobe-only-user-action) options can have potentially undesirable side effects.
preserve- Removes mapped Adobe groups. Users offboarded with this method will lose access to groups/products they were provisioned with the User Sync Tool. User data should not be impacted.
remove-adobe-groups- Removes all Adobe groups for offboarded users. This will also strip offboarded users of admin privileges.
remove- Remove offboarded users from the Console’s Organization Users list. Stored Creative or Document Cloud data will not be deleted. User settings in other Adobe products may be affected.
delete- Delete offboarded users from the underlying identity directory. User stored in Creative or Document Cloud will be subject to deletion.
max_adobe_only_users setting is used to protect an Adobe userbase from the
adobe_only_user_action from operating on a large number of users. If the limit defined by
max_adobe_only_users is exceeded, the Adobe-only user action is not executed at all. This can happen when something changes in the identity source or in the User Sync Tool configuration to impact the number of Adobe-only users identified during a sync.
max_adobe_only_users can be set to a hard number or a percent.
- Hard number - The limit is checked against the total number of Adobe-only users (as governed by the
- Percent - The limit is computed as a percentage of total users (as governd by the
|Total Adobe Users
|Adobe-only users are processed
|Do not process Adobe-only users
|Max is 200 (20% of 1000) so Adobe-only users are processed
|Max of 200 (20% of 1000) exceeded, so Adobe-only users are not processed
The User Sync Tool produces log messages describing what it is doing. Log messages are written to the console (
stdout) from which the tool was invoken and optionally to a log file.
Logging behavior is governed by the
File logging is toggled by
log_to_file. Set to
true to write log messages to the filesystem and
false to suppress file logging.
log_to_file is enables, then the other file-related options should be set as well.
Log files are written to files in a dedicated directory. The directory where logs are written is set by
This can be set to a path relative to the Sync Tool. For example, setting it to
logs when the Sync Tool is in the directory
/home/user-sync will write log files to the directory
file_log_directory can also be set to an absolute path.
File log messages are appended to the file defined by
file_log_name_format. This can be set to a static filename such as
user-sync.log. Or date/time information can be encoded using curly braces
Any of these formatting codes can be used.
For example, to set the filename to the date in
file_log_name_format can be set to
Note: The date is formatted at the beginning of the sync workflow.
Log files that don’t exist will be created automatically.
These options control the verbosity for log files and console (
stdout) output respectively.
Each level adds more information to the logs. These are the supported levels, in order from least verbose to most verbose. The higher verbosity levels include messages from lower levels. In other words
debug includes all other message types.
Only log critical errors that generally impact the overall sync process.
Log errors of any kind, even those that may not halt or negatively impact sync.
Warnings include messages that warrant attention but are not serious. Reasons include deprecated functionality, missing identity source data, etc.
Informational log messages. General information around sync behavior including summary info.
Any lower-level debug information: configuration options, raw API call payloads, etc. This information can be critical for debugging issues with User Sync Tool config, but can increase log file sizes significantly.
See Runtime Config for information about the Sync Tool’s
invocation_default options and how they interact with the tool’s command-line options.