Directory Sync Guide
Overview
Protected Trust Directory Sync enables your organization to synchronize the users and distribution lists in Active Directory with Protected Trust. Directory Sync periodically performs a one-way sync, from Active Directory to Protected Trust.
To access your Active Directory data, a light-weight Windows service, called the Protected Trust Connector, is installed in your domain network, as shown below. The Connector may be installed on multiple servers to achieve high availability.
Planning Your Directory Sync Strategy
As you make decisions on your specific configuration, please keep these points in mind.
- To synchronize users, Single Sign-on must also be enabled on your Protected Trust account.
- Distribution lists can always be synchronized, even without single sign-on.
- By default, users outside your organization (including guest users) that send a message to a distribution list that has “require sender authentication” (or similarly-named option) turned off can see the individual members of the distribution list.
- To limit this ability to only members of your organization, see the Privacy Consideration in Step 3, under the Filter property.
- Dynamic distribution lists are not supported.
- If a user attempts to send a message to a dynamic distribution list, the sender will receive a non-delivery report via email.
- At least one Connector must be running and connected for distribution list expansion to happen.
If all Connectors are offline when a user sends a message to a distribution list, the distribution list expansion will be queued and re-tried later. If the DL cannot be expanded, the sender will receive a non-delivery report via email.
Prerequisites
Directory sync requires the following software:
- Windows Server 2008 R2, or later
- This may be any server connected to your domain network.
- Microsoft .NET Framework 4.5
Additionally, configuration will require the following user accounts:
- Protected Trust API account
- Contact Protected Trust Support if you do not have an API user.
- (Optional) Active Directory service account, with read permissions
- This account will be used to retrieve the information from Active Directory.
Configuration
Installation involves three primary steps:
- Create an API Access Credential for the API User
- Install the Protected Trust Connector
- Configure Directory Sync
Step 1. Create an API Access Credential for the API User
Before installing the Connector, you will need an API access credential. An access credential consists of a randomly-generated access ID and key pair. The Connector will use this ID and key to authenticate with the Protected Trust service. To create a new access credential:
a) Sign-in to the Protected Trust web portal at app.protectedtrust.com
b) Click “User List.”
c) Find the API user and click on it.
d) On the left, click “API Access Credentials.”
e) Under “Generate New Access Credential,” enter a name, such as “AD Directory Sync”, and click “Generate.”
You will need to enter the access ID and key later, while installing the Connector.
Step 2. Install the Protected Trust Connector
The Protected Trust Connector is a light-weight Windows service installed on your domain network that reads data from your Active Directory and sends it to the Protected Trust service. To ensure high availability, install it on multiple servers. If no connectors are online for an extended period of time, user data will not synchronize and DL expansion will fail.
To install the Connector on your server:
a) Download the Connector from the Protected Trust admin web portal.
Sign-in at app.protectedtrust.com
b) Install the Connector on the desired Windows Servers.
c) (Optional, see note below) Set the “Log on” user for the new Windows service called “Protected Trust Connector.”
- a. Open the Windows Services window (Shortcut: +R à services.msc à Enter).
- b. Right-click the “Protected Trust Connector” service and click “Properties.”
- c. Click the “Log On” tab and enter the desired service account under “This account.”
- d. Click OK and restart the Windows service “Protected Trust Connector.”Note: In some cases, the default Local System account has enough rights to read from Active Directory already. In this case, it may not be necessary to set a Log on user.
d) From the Windows start screen, find and run “Protected Trust Connector (Configuration)”
e) Copy the newly created Access ID from the API Access Credentials page (opened earlier) and paste it into the “Access ID” textbox.
f) On the API Access Credentials page, click “Show” under the Access Key column. Copy the Access Key and paste it into the “Access Key” textbox.
If the access key area turns blank on the webpage, your session may have timed out. Refresh the page to re-authenticate and try clicking Show again.
g) On the Connector configuration screen, click “Save.” The program will verify the access credentials. If there was a problem, an error message should appear.
h) On the Connector configuration program, click the “Status” tab. Ensure that the status label says “Running & Connected.” If not, review the logs for an error message.
You may also view the Connectors page on the Protected Trust admin web portal for connection status. Sign-in at app.protectedtrust.com – Click Settings – Single Sign-On & User Sync – Connectors
i) Repeat installation on a second Windows server, if desired.
Step 3. Configure Directory Sync
Now that the Connector is installed and connected to the Protected Trust service, it is time to configure the synchronization with Active Directory.
a) On the Protected Trust admin web portal, navigate to the Directory Sync page.
Sign-in at app.protectedtrust.com – Click Settings – Single Sign-On & User Sync – Directory Sync
b) Click “New Directory Sync.”
c) Click “Sync with AD & Exchange.”
d) Enter the requested information on the form:
| Display Name | Choose any name that uniquely describes this directory sync configuration. E.g. “MYCOMPANY.LOCAL AD Sync” |
| Status | Enabled – When enabled, the directory sync will occur on the schedule defined by Full Sync and Incremental Sync below.Paused – When paused, the directory sync will not occur. |
| Full Sync | Select the interval to perform a full sync. During a full sync, a subset of data about each matching user and distribution list is sent to the Protected Trust service. |
| Incremental Sync | Select the interval to perform an incremental/differential sync. New and modified users and distribution lists will be updated. Deleted users and distribution lists will not be detected until the next full sync. |
| Run on Connectors | Typically, select “Default.” This option applies only if you wish to synchronize with multiple directories using different Connector installations. |
| Object Types | Select the type of objects to synchronize. Users – When checked, users will be synchronized. Single sign-on is required to synchronize users. Distribution Lists – When checked, distribution lists will be synchronized. Only the metadata about a distribution list is synchronized; the membership is expanded each time a message is sent to one. |
| Search Root | Enter the root object in Active Directory to synchronize. E.g.CN=Users,DC=example,DC=local |
| Filter | Enter the LDAP query filter for the objects you’d like to synchronize. Privacy Consideration: By default, users outside your organization (including guest users) that send a message to a distribution list that has “require sender authentication” (or similarly-named option) turned off can see the individual members of the distribution list. If you’d like to prevent this behavior, do one of the following:
|
| Domain Controller Hosts | List the domain controllers in your Active Directory. Place one host on each line. |
| Authenticate as Domain User | (Optional) If you did not specify the “Log on” user when installing the Connector, you may enter the username of the Active Directory service account here. This is account is used to read data from Active Directory. |
| Domain User Password | (Optional) The password for the Active Directory service account, if domain user is specified above. |
| Encryption | Use SSL – If checked, the Connector will use SSL encryption to connect to the Active Directory domain controller(s). |
e) Click “Save.”
Testing & Troubleshooting
To ensure that Directory Sync is working as expected, send a test message to a distribution list using Protected Trust. Ensure that each person in the distribution list receives the message via Protected Trust. You may also view the “Delivery Status” and “Proof of Delivery Log” for a message by opening the sent message using the Protected Trust web portal. After distribution list expansion has completed, each member of a recipient distribution list should be listed in the “Delivery Status” table.
Windows Event Log
The Connector records warnings and errors in the Windows Application event log with a “Source” value of “Protected Trust Connector.”
Log Files
The Connector retains detailed log files for approximately 14 days in the Windows temporary directory. The files typically have the filename format “C:WindowsTempptconnector-ABCDEFG-yyyy-MM-dd.log” Review these log files for indications of warnings, errors, or other unexpected conditions.
Monitoring
By default, all administrators in your organization will receive an email notification if a Connector goes offline. When the connector comes back online, each administrator will receive another email notification.
To control which administrators receive these notifications,
a) Sign-in at app.protectedtrust.com
b) Click “User List”
c) Select “Administrators” from the drop-down list
d) Click a user
e) Click Notifications, on the left
f) Check, or uncheck, “Connector” on the list
Click “Save”