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
• 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:
# Identifies all users in the "DirSyncLevel0" security group under the "DirSync" OU
dsquery * "OU=DirSync,DC=test,DC=authentic8,DC=com" ^
-filter "(&(objectCategory=User)(memberOf=CN=DirSyncLevel0,OU=DirSync,DC=test,DC=authentic8,DC=com))" ^
-scope onelevel
# Identifies all user objects directly under the "DirSync" OU
dsquery * "OU=DirSync,DC=test,DC=authentic8,DC=com" ^
-filter "(objectClass=User)" ^
-scope onelevel
# Identifies a user whose mail attribute is level0user@test.authentic8.com
dsquery * "" ^
-filter "(mail=level0user@test.authentic8.com)" ^
-scope subtree
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 |
| givenName | firstName | Optional |
SN | lastName | Optional |
| Required | ||
| userName | Required | |
| Mobile Phone | phone | Optional |
Important:
- Silo sets the end-user's Active Directory email address as both username and email address values in Silo
- Email and username fields are required primary keys in the Silo database
- While it is technically possible to map any Active Directory field to a given Silo field, the email and username values must be unique within the entire Authentic8 ecosystem
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 Silo Test
orgMappings Examples:
"orgMappings": [
{
"dn": "object_distinguished_name", // Replace with the target DN
"filter": "ldap_search_filter", // Replace with appropriate LDAP filter
"scope": "base", // One of: "base", "onelevel", or "subtree"
"a8Org": "a8_org_name" // Replace with actual A8 org name
},
{
// Example: Security Group (DirSyncLevel0) under OU (DirSync)
"dn": "OU=DirSync,DC=test,DC=authentic8,DC=com",
"filter": "(&(objectClass=User)(memberOf=CN=DirSyncLevel0,OU=DirSync,DC=test,DC=authentic8,DC=com))",
"scope": "onelevel",
"a8Org": "a8_org_name_1"
},
{
// Example: All users under OU (DirSync)
"dn": "OU=DirSync,DC=test,DC=authentic8,DC=com",
"filter": "(objectClass=User)",
"scope": "onelevel",
"a8Org": "a8_org_name_1"
},
{
// Example: Specific user by email
"dn": "", // Leave empty if not filtering by DN
"filter": "(mail=level0user@test.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": "sAMAccountName" // Suggest using a standard AD attribute for username
},
"email": {
"attribute": "mail" // Typically, 'mail' is used for email in AD
},
"firstName": {
"attribute": "givenName", // Or use "constant": "John" if hardcoding
"sync": true
},
"lastName": {
"attribute": "sn", // 'sn' = surname in AD
"sync": true
},
"phone": {
"attribute": "telephoneNumber", // Or use "constant": "123-456-7890"
"sync": 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 a full example based on the settings discussed above:
{
"SyncInterval": 60, // Interval in minutes
"orgMappings": [
{
"type": "SecurityGroup",
"key": "group_name", // AD group CN
"a8Org": "a8_org_name"
},
{
"type": "ou",
"key": {
"ou": "OU=ou_name,DC=domain,DC=com", // Fully qualified DN of the OU
"recursive": true
},
"a8Org": "a8_org_name"
},
{
"type": "attribute",
"key": {
"attribute": "department", // Any AD user attribute
"value": "Engineering"
},
"a8Org": "a8_org_name"
},
{
"type": "attribute",
"key": {
"attribute": "title",
"valueRegex": "Manager.*" // Regex match for titles like "Manager", "Manager II"
},
"a8Org": "a8_org_name"
},
{
"type": "catchall",
"a8Org": "default_org" // Fallback if no other mapping matches
}
],
"authToken": "AUTH_STRING12345", // Replace with actual auth token
"serverHost": "extapi.authentic8.com",
"serverPort": 443,
"fieldMappings": {
"userName": {
"attribute": "mail"
},
"email": {
"attribute": "mail"
},
"firstName": {
"attribute": "givenName", // Replacing broken key with valid structure
"sync": true
},
"lastName": {
"attribute": "sn",
"sync": true
},
"phone": {
"attribute": "telephoneNumber",
"sync": true
}
},
"breakerMode": false,
"breakerThreshold": 30 // Number of failures before breaking sync
}
7. Test Your Configuration
Open a Command Prompt or Powershell window, and navigate to the DirSync application folder: C:\Program Files (x86)\A8UserSync\A8UserSync.exe
Enter the following command: A8UserSync.exe -dryrun
The output will display any misconfigurations, which can be fixed 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