Synchronizing Users from Active Directory

Administrator -

Note: The instructions provided in this article apply to an installation of the AD Sync tool on a Windows server.

Introduction

You can synchronize your Active Directory User database into your Enterprise Account, via the AD Sync tool (a Python script, installed and executed from your network) that was developed for this purpose.

Synchronization Behavior

During the synchronization (through secure requests):
  • 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 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.

Scheduled Synchronization

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)

Important: Read carefully the following before going forward with the AD Sync tool implementation.
  1. Prepare your Active Directory and your Enterprise Account environments for a proper synchronization:
  2. Install the AD Sync tool.
  3. Configure the AD Sync tool.
  4. Execute the AD Sync script – manually or through a scheduled task.

Preparation

Create groups in your Enterprise Account

Each synchronized user will be necessarily assigned to a Group in your Enterprise Account (see Managing Groups).

If you wish to divide users into several groups, you must pre-create them in your Enterprise Account. The AD Sync tool can be configured to determine group names using one of these methods:
  • By default: use the name of the smallest user object containers.
    • For example: with users CN=username,OU=Accounting,DC=example,DC=com and CN=username,OU=Support,DC=example,DC=com, the names of the groups would be "Accounting" and "Support".
  • Alternative choice: use the value of a specific attribute of the user objects.
    • For example: if you choose the user attribute "l" for this (to group users by location/city) and the value of this attribute is "New York" or "Montreal" depending on the user, the names of the groups would be "New York" and "Montreal".
Important: The setup corresponding to this choice will be done in a configuration file through a further step of this procedure. However, everything must be perfectly preset for a good match between your Active Directory grouping elements and your Enterprise Account groups. Otherwise users will be assigned to the default group defined in your Enterprise Account.

Verify email addresses in your Active Directory

E-mail Addresses must exist in all user accounts among the concerned Active Directory users.
Attention: Users without an e-mail address will not be imported to your Enterprise Account.

Arrange your fax number assignment plan

If you subscribed for the Fax Service, the assignment of fax numbers with users can be done automatically through the AD Sync script.

Here are the conditions to respect:
  1. The fax numbers must have been added to your Enterprise Account prior to running the script (see Managing Fax Numbers).
  2. The 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.
The assignment mechanism behavior will then be the following:
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)...

Installation

Note: It is not required to have the script installed on the Active Directory server directly. Any computer on the network that can access both your Active Directory server and the Internet can run the script, as long as it is allowed to perform outbound TCP connections to your Enterprise Account (https, port 443) and queries to the Active Directory LDAP interface (LDAP, 389 by default).
  1. Install the 32-bit version of Python 2.7.3.
    Download available here: https://www.python.org/download/releases/2.7.3/ – search for Windows x86 MSI Installer (2.7.3) (sig).
    Note: More recent minor Python versions – i.e. 2.7.x, with x > 3 – should also be supported, however they have not been officially tested with the AD Sync tool.
  2. Download the latest version of the AD Sync package file (see Download page).
  3. Decompress the file in the folder or your choice (<adsync_home>).
You can now configure the AD Sync tool according to your needs (see the procedure below).
Important: If you need to modify the Python modules (.py files) for further customization, make sure they are saved in UTF-8 format.

Configuration

  1. Create an Access Token that will be used for allowing the AD Sync script to manage your user directory:
    1. From your Enterprise Account, select Access Tokens via the navigation bar.
    2. Create an Access Token with the two following permissions:
      • Manage users
      • Query user directory
    3. Copy the created token string for use in the following configuration.
  2. Edit the AD Sync tool's configuration file: <adsync_home>\config\default.yaml:
    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.
    1. Configure connection and access settings for your Enterprise Account:
      You need to enter:
      • 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.
      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:
      fax_service:
        address: "https://portal.xmedius.com/enterprises/exampleinc"
        access_token: 193e6f8bd084xxxxxx3c565bedbxxxxxx
    2. Optionally [since AD Sync version 1.0.4], you can disable the automatic sending of password setup emails to newly created users (enabled by default):
      • To disable emails, set the value:
          disable_emails: true
      • Default value is false.
    3. Configure connection and authentication settings for your Active Directory:
      You need to enter:
      • The address of your LDAP server (Active Directory),
      • 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.
      For example:
      active_directory:
        address: ADServerName
        port: 389
        username: Domain\User
        password: UserPassword
      Important: If you want the AD Sync script to remove accounts that have been deleted, the user specified here must also 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.
    4. 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:
      • 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.
        For example:
            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.
      • The 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 Enterprise Account.
        For example:
            query_for_deleted_users:
              -
                base: "CN=Deleted Objects,DC=example,DC=com"
                scope: "SUBTREE"
                filter: "(&(objectClass=user)(isDeleted=TRUE))"
      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.
    5. You can optionally modify the mapping between your Enterprise Account attributes and your Active Directory attributes (see Attribute Mapping).

Running the script

The AD Sync script can be run:

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.

First Synchronization

The first time the script will be executed, all targeted Active Directory users will be imported into your Enterprise Account. In the XMedius Cloud portal interface, all these users will appear with the tag External User.
Note: The first synchronization may take some time to complete, depending on the number of users.

All users will receive an email to configure their XMedius Cloud user account password (which is not managed through Active Directory).

Subsequent Synchronizations

From the second execution of the script, only the users that were added, modified or deleted in your Active Directory will be synchronized to your Enterprise Account (and tagged External User).
Attention: It is not recommended to alter the search queries within the AD Sync tool configuration file between two synchronizations. This would lead the 'changes counter' in the AD Sync tool database to become invalid and result in unexpected synchronization behaviors.

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.

User Management

You can choose to further modify the synchronized users (tagged External User) either through subsequent executions of the AD Sync script, or directly through the XMedius Cloud portal interface.
Important: A subsequent execution of the AD Sync script will override any modification that was performed through the XMedius Cloud portal interface. That said:
  • 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.

User Deletion

The mechanism of deletion of cloud user accounts highly depends on your company processes and on the way you implemented the queries within the AD Sync tool configuration file (see Configure the search parameters to retrieve users (and deleted users) in your Active Directory).
Note: When a user is deleted, his faxes are not removed from the cloud system (as long as they are retained according to your fax retention scheme – see Fax Retention). Therefore, if the user is re-added to the Active Directory and the AD Sync script runs again, that user will be re-associated to his faxes, provided his e-mail address is set in Active Directory exactly as it was initially.
Attention: If you delete any synchronized user directly from the XMedius Cloud portal interface, this will remove the user's access and the visibility of that account in the portal. The account will not be automatically re-inserted to the enterprise at the next synchronization.

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.

Running the script manually

You can run the script manually using the following command line from the folder where the AD Sync script resides:
<python_home>\python.exe adsync.py
If you want to run the script using a different configuration file (e.g. new_config.yaml):
<python_home>\python.exe adsync.py <path>\new_config.yaml

Running the script through the Windows Task Scheduler

You can run the script as a planned event in the Windows Task Scheduler.

  1. Create a scheduled task with the following properties:
    • The script must run using an account with full control over the folder containing the script file.
    • Ensure to select the option to run whether the user is logged on or not.
  2. Add the following action configuration:
    • Action: Start a program
    • Program/script: <python_home>\python.exe
    • Add arguments:
      • adsync.py (mandatory)
      • <path>\new_config.yaml (optional, if you need to use a different config file)
    • Start in: <adsync_home>

Log File

The script produces a log file in the <adsync_home>\logs folder containing the various synchronization results.

Advanced/Optional Configurations

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).

A search node contains 3 elements (base, scope, filter) and always starts with a dash ("-" in its own line), as shown below:
      -
        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>"
Important: Pay special attention to line indentations as they define the functional structure of the query.

Excluding Users from Queries

You can exclude users from a query, based on values found in the Active Directory user attributes. As 4th search element within the query, enter the exclusions using the following syntax:
      -
        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>"
Important: Pay special attention to line indentations as they define the functional structure of the query.
Wildcards are supported in the values to match. Logical operator OR will be applied between criteria. For example:
        exclusion :
          mail:
            - "FederatedEmail*"
            - "SystemMailbox*"
            - "DiscoverySearchMailbox*"
will exclude from the search all users whose email address was generated automatically by Active Directory.

Attribute Mapping

If you need to change the mapping between your Enterprise Account attributes and your Active Directory attributes, you can do it through the section attributes_mapping found in the AD Sync tool's configuration file (see Edit the AD Sync tool's configuration file):
#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 configuration file:
      address: "streetAddress"
      city: "l"
      company_name: "company"
      country: "co"
      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"
Have more questions? Submit a request

Comments

Powered by Zendesk