Authentic8 Support

Introduction

Authentic8’s Active Directory Sync Tool (“DirSync”), is a Windows service that installs on an Active Directory server and synchronizes account data from Active Directory to Silo. Appropriately flagged users in Active Directory can be moved, added or updated to, or deleted or suspended from Silo. Once the Sync Tool is properly configured, user contact information can be added, deleted, suspended, or updated without requiring an administrator to log into Silo.

System Requirements

1. 10 MB of available disk space
2. Clear Active Directory server communication with the Authentic8 solution over port 443 (TLS) (See Firewall Rules for details.)
3. A sync token (Get this from Authentic8 Support.)
4. A dsquery * command that produces the user set you want to sync
5. DirSync software
6. TLS 1.2 connections*

*NOTE: Effective March 30 2020, our products will only support TLS 1.2 connections and will cease support for TLS 1.1. If you use one of our native applications, please ensure their version exceeds the minimum required to support TLS 1.2  and that any in-line network infrastructure that connects to our servers has been configured to use TLS 1.2

Details

The Active Directory Sync Tool syncs user objects, guided by a config file in JSON format (ada8sync.config). DirSync determines which Active Directory Organizational Units (OUs) and Security Groups are to be synced and make changes to Silo as needed. Silo never makes changes to Active Directory: all changes are pushed from Active Directory down to Silo.

DirSync uses the LDAP (Lightweight Directory Access Protocol) query to determine what should be done in Silo. The LDAP query statement can be verified with dsquery * command. Once DirSync obtains the query results from Active Directory, it modifies the mapped org by adding, deleting, moving, or suspending (AD disable) users.

The config file accepts definitions of one or more orgs that should be synchronized and executes those changes in order.

Installation and Configuration

To use the Active Directory Sync Tool:

1. Obtain the installer software and authorization token from Authentic8
2. Install the software on a domain member server
3. Define a set of users to sync
4. Define the LDAP query statements to obtain the set of users you want to sync and verify them with dsquery * command
5. Determine which AD characteristics of those you would like to sync
6. Adjust the configuration file
7. Test your configuration
8. Enable the service

1. Obtain DirSync Installer and Get an Authorization Token

Click here to obtain the DirSync installer software. Check its file signatures here. To generate a token, designate a user ID in your Silo environment as a service account used for syncing.  Contact Authentic8 Support to obtain your token and specify the user you would like to use for syncing.  

2. Install DirSync on a Domain Member Server

Double-click the installer. Because the installation completes silently, review the Windows Services panel to ensure the Authentic8 User Synchronization Service is running. Turn the service off until you are ready to switch to production (You can access this background process, identified as “Authentic8 User Synchronization Service,” using the Task Manager).

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

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

5. Decide Which AD Characteristics to Sync

The Active Directory Sync Tool can synchronize fields in Silo as follows:

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. Adjust the Configuration File

The main configuration file is C:\Program Files (x86)\A8UserSync\ ada8sync.config and is described in JSON format. Edit this file, setting the following fields:

• SyncInterval Sync interval frequency, in minutes. The initial recommended setting in 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 specificity of how objects will be recognized for syncing. Filter terms can be set essentially as search terms for entire groups down to individual users.
• 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 users of this block must follow. For example, the path for a Silo parent of “Acme Enterprises” and a sub-org called “IT” is: Acme Enterprises/IT

    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 an authentication token provided by Authentic8 Support.
• serverHost This is the Silo API endpoint. It is not configurable, and should be set to Enter extapi.authentic8.com.
• serverPort The default server endpoint listening port value is 443.
• breakerMode The breakerMode Boolean toggles the circuit breaker off or on.
• breakerThreshold Because DirSync can erase or change large numbers of Silo user objects silently and automatically, a “circuit breaker” functionality is provided. If breakerMode is TRUE and DirSync changes the percentage of objects set in breakerThreshold, DirSync aborts the sync and logs an error message in the application log. The breaker threshold sets the percentage of user objects that must be changed to trigger the breaker. While useful in production environments, this feature can be counterproductive in test and configuration runs that involve small user groups. It is a best practice to leave breakerMode toggle to false until the user group is large and the sync parameters well defined.

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 (both the native Windows cmd.exe and CygWin bash environment work) and navigate to the DirSync installation folder. Enter the following command:

A8UserSync.exe -dryrun

The output indicates any misconfigurations, which you can fix with changes to 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 a user is disabled in Active Directory, that user is suspended in Silo. 
• A user deleted in Active Directory (or removed from a security group or OU being synced) is subsequently deleted from Silo. 
• Moving a user from one synced OU to another synced OU moves that user in Silo. 

Warning: Silo does not support username changes. If a user’s email address is changed in Active Directory, that user is purged and recreated in Silo.

10. The 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 installs by default in the following 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 ­dry run 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 Files

When active, DirSync logs events, sync errors, and other information. These are available in the Windows Event Viewer, and are filed at: C:\Windows\System32\winevt\Logs\Application.evtx. Opening this file opens the Event Viewer. 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 you complete the first one or two.
• Leave breakerMode false until DirSync has enough users 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.

Additional Notes  

Please contact Support if you have any additional questions and/or require further information.