Introduction

Authentic8’s Active Directory Sync Tool (DirSync) is a Windows-based utility that leverages our User Provisioning API as a way to import Active Directory user accounts over to Silo. Appropriately flagged Active Directory accounts can be moved, updated, suspended, and deleted using the DirSync utility.

 

System Requirements

• 10 MB of available disk space

• Full access to the Active Directory server

• User API Token (provided by Authentic8 Support)

• dsquery command-line tool installed that

• DirSync software download

• TLS 1.2 protocol enabled

 

Important: Effective March 30, 2020, Authentic8 will only support TLS 1.2 connections, and will cease to accept TLS 1.1 connection requests. Any in-line network infrastructure connecting to our servers must also be configured to permit the use of the TLS 1.2 secure protocol.


Overview

DirSync synchronizes Active Directory user objects via the LDAP protocol, and based on the parameters set within the JSON-formatted config file (ada8sync.config). The config file is able to accept one or more org definitions to be synchronized in sequential order. Its functionality determines which Active Directory Organizational Units (OU) and Security Groups need to be synchronized, and will import the changes to Silo accordingly.

Please note that Silo will not make any changes to your Active Directory instance, as it will simply implement new or pending changes captured from Active Directory.



Installation and Configuration

 

1. Obtain DirSync Installer and API Authorization Token

Download the DirSync installer; you may verify its file signature here.

To request an API token, a Silo Admin will need to designate a Silo service account within your Silo organization structure, then contact Authentic8 Support  

2. Install DirSync

Execute the installer file on the host machine, which can either be a domain server with full access to Active Directory, or a Windows workstation with Remote Server Administrator Tools installed

 

3. Define a Set of Users to Sync

For a typical configuration, this is a security group containing the users you intend to have access to Silo. This can be an existing group or a new one. You can define the group using any searchable criterion, such as Security Group, OU, name, sub-string, and so forth.

 

4. Define the LDAP query statements and verify them with dsquery *command

See the Microsoft dsquery * page for more details.

 

Examples:

dsquery * "OU=DirSync,DC=wcdev,DC=authentic8,DC=com" -filter "(&(objectCategory=user)(memberof=CN=DirSyncLevel0,OU=DirSync, DC=wcdev,DC=authentic8,DC=com))" -scope onelevel 

# Identifies all users in a Security Group (DirSyncLevel0)

  

dsquery * "OU=DirSync,DC=wcdev,DC=authentic8,DC=com" -filter "(objectClass=User)" -scope onelevel 

# Identifies all users under OU (DirSync)

 

 dsquery * "" -filter "(mail=level0user@wcdev.authentic8.com)" -scope subtree 

# Identifies a user whose mail is level0user@wcdev.authentic8.com

 

Important: Only the root (forestroot or domainroot), -filter, and -scope parameters are supported.

 

5. Decide Which Active Directory Characteristics to Sync
DirSync can synchronize fields as follows:

 

AD User Object Field
Silo User Field
Requirement
givenNamefirstNameOptional

SN 		lastNameOptional
mailemailMandatory
mailuserNameMandatory
Mobile PhonephoneOptional



IMPORTANT

  1. Silo takes users’ Active Directory email address to be their username and email address in Silo.
  2. Email and username fields are mandatory primary keys in the Silo database. If these values change in Active Directory, Silo deletes the account and adds a new account.
  3. While it is technically possible to map any Active Directory field to any Silo field, the email and username values must be unique across all of Authentic8’s customers.

 

6. Update the Configuration File

DirSync's configuration file is located in: C:\Program Files (x86)\A8UserSync\ ada8sync.config

You will need to edit this file using the following fields:


  • SyncInterval Sync interval frequency in minutes. The default recommended setting is 60 minutes
  • orgMappings This is a series of blocks where dsquery * to org mappings are made

The fields defined in orgMappings are:

  • dn — The object’s unique distinguished name.
  • filter — This field controls the parameters of how objects will be recognized for synchronization. Filter terms can essentially be set as search terms for entire group down to individual user objects
  • scope — This field defines the AD search scope. Possible values are: base, one-level, and subtree, or any combination of these.
  • a8Org — This is the org path target in Silo. For example, the value for a Silo parent organization labeled Acme Enterprise

 

    orgMappings Examples:

"orgMappings": [

    { "dn":"object_distinguished_name",

      "filter":"ldap_search_filter",

      "scope":"base"|"onelevel"|"subtree",

      "a8Org":"a8_org_name"},

    // Example. Security Group (DirSyncLevel0) under OU (DirSync)

    { "dn":"OU=DirSync,DC=wcdev,DC=authentic8,DC=com",

      "filter":"(&(objectClass=User)(memberof=CN=DirSyncLevel0,

               OU=DirSync,DC=wcdev,DC=authentic8,DC=com))",

      "scope":"onelevel",

      "a8Org":"a8_org_name_1"},

    // Example. Users under OU (DirSync)

    { "dn":"OU=DirSync,DC=wcdev,DC=authentic8,DC=com",

      "filter":"(objectClass=User)",

      "scope":"onelevel",

      "a8Org":"a8_org_name_1"},

    // Example. User whose mail is level0user@wcdev.authentic8.com

    { "dn":"",

      "filter":"(mail=level0user@wcdev.authentic8.com)",

      "scope":"subtree",

      "a8Org":"a8_org_name_1"}

  ]

 

Continue making blocks until you have configured all OUs and orgs


  • fieldMappings This block defines which AD characteristics are synchronized to Silo

    fieldMappings example:

"

fieldMappings": {

  "userName": { "attribute":"domain_attribute" },

  "email" : { "attribute":"domain_attribute" },

  "firstName" : { "constant":"constant_value" or "attribute" : "domain_attribute", "sync" : true | false },

        "lastName" : { "constant":"constant_value" or "attribute" : "domain_attribute", "sync" : true | false },

        "phone" : { "constant":"constant_value" or "attribute" : "domain_attribute", "sync" : true | false },

  },

  • authToken This is the API authentication token provided by Authentic8 Support
  • serverHost This is the Silo API endpoint, which should always be set to: extapi.authentic8.com
  • serverPort The default server endpoint listening port value is 443
  • breakerMode The breakerMode Boolean toggles the circuit breaker On or Off
  • breakerThreshold Because DirSync can quickly change large numbers of Silo user accounts, a “circuit breaker” functionality is provided as a safety blanket. If breakerMode is set to TRUE and DirSync changes the percentage of objects set in breakerThreshold, DirSync will abort the sync and record an event information in the Windows Event - Application logs

    The breaker threshold sets the percentage of user object changes to trigger the breaker. While useful in Production environments, this feature can be counterproductive in test and configuration runs that involve small user groups. For Best Practice, set breakerMode to False until the user group is large enough with a well-defined sync parameters

 

Here is an example file based on the settings discussed above:

{

"SyncInterval": 60,

"orgMappings": [

// Security Group type

{ "type": "SecurityGroup",

"key":"group_name",

"a8Org":"a8_org_name" },

// ou type

{ "type": "ou",

  "key": { "ou":"OU=ou_name", "recursive":true },

  "a8Org":"a8_org_name" },

// attribute type using constant attribute value

{ "type": "attribute",

  "key": { "attribute":"attribute_name", "value":"attribute_value" },

  "a8Org":"a8_org_name" },

// attribute type using regex value

{ "type": "attribute",

  "key": { "attribute":"attribute_name", "valueRegex":"regex_value" },

  "a8Org":"a8_org_name" },

// catchall type

{ "type": "catchall",

  "a8Org":"a8_org_name" }

  ],

"authToken": "AUTH_STRING12345",

"serverHost": "extapi.authentic8.com",

//field mappings

"fieldMappings": {

     "userName": { "attribute":"mail" },

     "email" : { "attribute":"mail" },

     "firstName" : { "constant":"constant_value" : "domain_attribute", "sync" : true},

     "lastName" : { "attribute" : "sn" },

     "phone" : { "attribute" : "domain_attribute", "sync" : true},

     },

"serverPort": 443

    "breakerMode":false

    "breakerThreshold":30

}

 

7. Test Your Configuration

Open a Command Prompt window (Powershell also works) and navigate to the DirSync installation folder: C:\Program Files (x86)\A8UserSync\A8UserSync.exe


Enter the following command: A8UserSync.exe -dryrun

 

The output will display any misconfigurations, which you can fix by updating the config file

 

8. Enable the Service

When you’re confident in your configuration, return to the Windows Services panel you visited in Step 2 and re-enable the A8UserSync service.

 

9. Changing Existing Users

Here are some examples of user configuration changes:


  • If a mobile number is updated in Active Directory, the number change is pushed to Silo
  • If an account is disabled in Active Directory, that account is suspended in Silo
  • A deleted account in Active Directory (or removed from a Security Group or OU) is subsequently deleted from Silo, and skips the Trash Bin
  • Moving an account from one synchronized OU to another will move that account in Silo, assuming that the target OU is also configured in the config file


10. A8UserSync.exe Tool

Although DirSync runs quietly in the background, you can invoke it manually from the command line to test configurations. The manual executable, A8UserSync.exe is available in the following folder path:

 

C:\Program Files (x86)\A8UserSync\A8UserSync.exe


  • You must invoke A8UserSync from the command line with a parameter. If you do not set a parameter, you will receive a basic help message.
  • Use A8UserSync for basic configuration, test, and validation
  • You can validate a config file using the ­verify filename parameter. This parses the config file to determine its syntactic validity
  • Once you have validated a config file, you can test it against a test (or live) environment using the ­-dryrun parameter. This simulates a sync from the command line, and produces a report of successes or problems encountered in the run. No object data is changed.
  • If you have a valid configuration that produces no errors in a dry run, use the ­sync command to perform single manual syncs
  • When you are satisfied with your config file, save it as ada8sync.config in the same directory as A8UserSync.exe

 

11. Log Events

DirSync logs events, sync errors, and misc information are available in the Windows Event Viewer > Application logs. The Source ID for DirSync events is A8UserSync

 

12. Best Practices

  • Start with a small test group until you are comfortable with the system. Add more orgs after successfully completing one or two
  • Leave breakerMode set to False until DirSync has enough user accounts to work with, so that simple updates do not trigger the breaker
  • To make the interval between syncs shorter than the initial recommended settings, time the syncs to learn how long they take so that the process does not start a new sync before finishing the previous one



Please contact Support for any additional questions