The AD Sync Tool enables to import your Active Directory users into your XMedius cloud platform – and to subsequently synchronize (i.e. update/delete) these users on your XMedius cloud platform according to the changes that may occur in your Active Directory user database.
The AD Sync tool is provided in the form of a Python script (and modules) and is intended to be executed from your network.
- All user creation/modification/deletion actions performed via Active Directory will be replicated toward your Enterprise Account.
- Any user Disabled in Active Directory will be deleted on your Enterprise Account.
- If you subscribed for the XM Fax Service, all assignments/unassignments of fax numbers to user accounts will be applied in your Enterprise Account.
For more specific behaviors to be aware of before using the AD Sync tool, see Before running the script.
You may require to execute the synchronization script at regular intervals, in order to automatically keep your Enterprise Account up-to-date according to changes occuring in your Active Directory. To achieve this, it is possible to add the script execution command to a scheduled task, for example using the Windows Task Scheduler.
Planning (Before you Begin)
Create groups in your Enterprise Account
Each synchronized user will be necessarily assigned to a Group in your Enterprise Account (see Managing Groups).
- By default: use
the name of the smallest user object containers.
choice: use the value of a specific attribute of the user objects.
Verify email addresses in your Active Directory
Arrange your fax number assignment plan
If you subscribed for the XM Fax Service, the assignment of fax numbers with users can be done automatically through the AD Sync script.
- The fax numbers must have been added to your Enterprise Account prior to running the script (see Managing Fax Numbers).
facsimileTelephoneNumber attribute of each
Active Directory user targeted for fax number association must contain one of
these fax numbers (if needed, it is possible to map the fax number to another
Active Directory attribute by modifying the AD Sync script configuration file).
Important: Fax numbers entered in your Active Directory do not need to have a specific formatting, as long as all their numeric digits (including country code) match fax numbers of your Enterprise Account. For example, 15551234567 or 1-555-123-4567 in Active Directory will match +1 (555) 123-4567 in the Enterprise Account.
|If the fax number...||The user...||And the user...|
|is tagged Individual in your Enterprise Account||will be assigned to the number...||for automatically receiving incoming faxes.||will use this number...||as the originating number of his outgoing faxes (shown as the "from" number of cover sheets and set as the originating number on the fax call).|
|is tagged Shared or is the Main Number in your Enterprise Account||will NOT be assigned to the number...|
|does not match an existing number of your Enterprise Account||will use the Main Number (when set)...|
The AD Sync Tool can be installed on any computer having access to both your Active Directory server and your XMedius Cloud account. That said, this computer must meet a few additional requirements.
- Create an Access Token that will be used for allowing the AD Sync script to manage your user directory:
Edit the AD Sync tool's configuration file:
Note: Enter functional values to replace comments starting with #####, always keeping one space character afer the colon.Important: All line indentations must be kept unchanged as they define the functional structure of the file.
Configure connection and access settings for your
You need to enter:
Note: Use the [domain] that corresponds to the region of your enterprise account (i.e. xmedius.com for North America or xmedius.eu for Europe).For example:
- The full URL used to reach your account on the Cloud platform (in the form https://portal.[domain]/enterprises/[enterprise_account]), and
- The above created Access Token.
fax_service: address: "https://portal.xmedius.com/enterprises/exampleinc" access_token: 193e6f8bd084xxxxxx3c565bedbxxxxxx
[since AD Sync version 1.0.4], you can disable the
automatic sending of welcome/password setup emails to newly created users
(enabled by default):
Configure connection and authentication settings for your
You must enter:
- The address (including the port) of your LDAP server (Active Directory) – LDAPS protocol is supported (if not specified, ldap:// will be used by default),
- The name of an account with read only privileges on your Active Directory and on the Deleted Objects container, and
- The password of the user specified above.
active_directory: address: ldaps://ADServerNameOrIP:Port username: Domain\User password: UserPasswordNote: If you are using LDAPS, you can optionally enable the validation of the LDAP server certificate: for this, set the verify_cert parameter to true and specify the server CA store path in the ca_file parameter (PEM format). The path can be absolute or relative to the adsync.py file, and the path separator must be double backslashes \\.Important: If you want the AD Sync script to remove accounts that have been deleted, the user specified here must have read privileges on the Deleted Objects container. In a typical Active Directory deployment, non-administrator users cannot read the Deleted Objects container. To grant this access, refer to Changing permissions on a deleted object container at http://technet.microsoft.com/en-us/library/cc816824(v=ws.10).aspx.
Configure the search parameters to retrieve users (and
deleted users) in your Active Directory:
#Below are default search parameters for active directory search_nodes:There are two query sections to configure carefully according to your needs/policies:
Tip: For more advanced information on AD Sync tool queries (e.g. to extend/refine searches using multiple queries or by defining exclusions), see User Query Options.Restriction: LDAP referrals are not supported by the AD Sync tool. Any LDAP referrals returned by the queried base will be skipped.
query_for_users section is intended to
target the only containers in which user creations and modifications will be
synchronized to your Enterprise Account – through one or several queries.
query_for_users: - base: "CN=Users,DC=example,DC=com" scope: "SUBTREE" filter: "(&(objectCategory=person)(objectClass=user))"Remember: Any Active Directory Disabled user found through this query section will be deleted from your Enterprise Account at the next synchronization.Important: If a user is moved out of any of the queried containers between two synchronizations, it will become – and remain – an unsynchronized orphan in your Enterprise Account, whatever happens with the user on its new Active Directory location.
query_for_deleted_users section is
intended to target the containers regrouping users that are identified as
"deleted" on the Active Directory side and need to be deleted from your
query_for_deleted_users: - base: "CN=Deleted Objects,DC=example,DC=com" scope: "SUBTREE" filter: "(&(objectClass=user)(isDeleted=TRUE))"
- The query_for_users section is intended to target the only containers in which user creations and modifications will be synchronized to your Enterprise Account – through one or several queries.
- You can optionally modify the mapping between your Enterprise Account attributes and your Active Directory attributes (see Attribute Mapping).
- Configure connection and access settings for your Enterprise Account:
Running the script
- Manually (see Running the script manually)
- Automatically (see Running the script through the Windows Task Scheduler)
A synchronization log file is also available for troubleshooting purposes (see Log File).
Before running the script
Please note and remember the following before running the AD Sync script.
All users will receive an email to configure their XMedius Cloud user account password (which is not managed through Active Directory) – unless you disabled the sending of such emails.
If a query change is however required, you can delete the database.db file from the <adsync_home> folder in order to reset the counter and perform the whole synchronization of all users and assignments at the next execution of the script.
- The override will only occur on users whose object was modified on your Active Directory (unless a full synchronization occurs, which will reset all users).
- Only the properties included in the AD Sync mapping configuration (see Attribute Mapping) will be overridden.
However, to modify user properties such as the Role or the Time Zone (both not included by default in the mapping), you will necessarily need do it from the XMedius Cloud portal interface.
You can still create additional users via the XMedius Cloud portal interface (i.e. outside of the AD Sync scope), but these users will need to be fully managed afterwards via the portal (they will not be affected by the AD Sync script). You will easily recognize such users as they will not be tagged External User.
However in that situation, if you modify the user's object from your Active Directory, the AD Sync script will detect the modification and re-create the user account in the Enterprise Account. The user will then receive a new invitation email to complete the account creation (unless you disabled the sending of such emails).
Running the script manually
<python_home>\python.exe adsync.py <path>\new_config.yaml
Running the script through the Windows Task Scheduler
Create a scheduled task with the following properties:
Add the following action configuration:
User Query Options
Some options are available when configuring the queries to retrieve users and deleted users from your Active Directory for synchronization to your Enterprise Account.
All of them apply to both the query_for_users and query_for_deleted_users sections found in the AD Sync tool's configuration file (see Configure the search parameters to retrieve users (and deleted users) in your Active Directory).
Multiple User Queries
You can extend your queries by using several search nodes within the same section (query_for_users or query_for_deleted_users).
- base: "<base_1>" scope: "<scope_1>" filter: "<filter_1>" - base: "<base_2>" scope: "<scope_2>" filter: "<filter_2>" - base: "<base_3>" scope: "<scope_3>" filter: "<filter_3>"
Excluding Users from Queries
- base: "<base>" scope: "<scope>" filter: "<filter>" exclusion : <AD_attribute_1> : - "<value_or_pattern_1_1>" - "<value_or_pattern_1_2>" <AD_attribute_2> : - "<value_or_pattern_2_1>" - "<value_or_pattern_2_2>"
exclusion : mail: - "FederatedEmail*" - "SystemMailbox*" - "DiscoverySearchMailbox*"will exclude from the search all users whose email address was generated automatically by Active Directory.
#Attribute mapping for portal attributes vs active directory attributes attributes_mapping:
- The following
mapping is used to assign the users to a
Group in your Enterprise Account by
retrieving a relevant value from your Active Directory:
group_id: "ExtractGroupNameFromDn"Note: The default attribute "ExtractGroupNameFromDn" automatically extracts the name of the second to last element in the user's Distinguished Name. This corresponds to the smallest container in which the user object is stored. For example, in CN=username,OU=Accounting,DC=example,DC=com, it will return the value: Accounting.
Otherwise, you can use an attribute of the Active Directory user object instead, for example: "department". You must however ensure that the chosen Active Directory attribute will contain a relevant value for all user objects.
- Unless you have
specific needs, the rest of the mapping should remain as provided in the
address: "streetAddress" city: "l" company_name: "company" country: "c" email: "mail" external_id: "objectGUID" first_name: "givenName" job_title: "title" language: "preferredLanguage" last_name: "sn" main_fax_number_id: "facsimileTelephoneNumber" mobile_number: "mobile" phone_number: "telephoneNumber" state: "st" username: "sAMAccountName" zip_code: "postalCode"