Overview
Teramind's Active Directory integration imports your organization's users, computers, groups, and organizational units (OUs) directly into the Teramind Dashboard. Once connected, employee profiles stay in sync with your directory - departments, group memberships, and attributes like names, email addresses, phone numbers, and job titles - so monitoring policies and reports always reflect your actual org structure.
There are two ways to configure an integration:
Option 1 - Standard Approach: Configure the integration through the form - connection fields, pickers, and attribute mapping. This covers typical setups and is what most organizations should use.
Option 2 - Script-Based Approach: Configure the integration as a JSON document using the External sync script option, for scripted, custom sync logic in advanced deployments.
Prerequisites
Before you begin the set up process, have the following ready:
LDAP server address (domain controller's IP or hostname) and port. Usually, port
389is standard for LDAP and StartTLS; port636is standard for LDAPS.A service account with read access to the directory (e.g.,
[email protected]). A dedicated read-only account is recommended.Your CA certificate (PEM format), if you use LDAPS with a private or internal certificate authority.
Teramind admin access to the dashboard.
You can configure multiple directory integrations - each domain appears as its own row in the list.
Option 1: Standard Approach
In this standard approach, you configure the integration through the form - connection fields, pickers, and attribute mapping. This covers typical setups and is what most organizations should use.
Step 1: Add the Integration
1. From the Configurations > Settings > Active Directories page, click + Setup new integration.
2. Fill in the following fields. Fields marked (optional) can be left at their defaults:
Domain name (required): Enter your directory domain (e.g.,
emu.local).LDAP server (required): Enter the IP address or hostname of your domain controller. For example,
52.101.22.12ordc01.mydomain.local.LDAP port (required): Enter the server port. The standard port for LDAP and StartTLS encryption is
389, while LDAPS uses636. In this example we are using LDAPS, so the port is636.Login (required): Enter the service account - a dedicated read-only account is recommended. You can specify the login as a UPN, a distinguished name, or a plain account name. For example:
[email protected](UPN format),CN=Administrator,CN=Users,DC=emu,DC=local(distinguished name), oradministrator(account name). If you use a plain account name, the domain name of the integration is appended automatically to form the UPN.Password (required): Enter the service account password. When editing the integration later, this field shows Unchanged - only enter a value if you want to update it.
Encryption method (required): Select the encryption your directory server requires:
LDAPS: Encrypts the connection with TLS from the start. Uses port
636. Recommended for production - this is what we use in this example.StartTLS: Starts unencrypted on port
389, then upgrades the connection to TLS. Use when your directory server is configured for StartTLS.None: No encryption - credentials and directory data are sent in clear text. Use only for testing on isolated networks.
LDAP certification validation type (required): Select how strictly the server's certificate is validated:
Accept valid: Require a valid, trusted certificate - the connection fails if the server's certificate can't be validated against a trusted CA. The strictest option; use it when your server has a properly CA-signed certificate.
Accept any: Don't validate the certificate - any certificate (or none) is accepted. Use only for testing on isolated networks, since it offers no protection against server impersonation.
Accept specified or valid: Trust the certificate you uploaded under Upload LDAP trusted certificate, or a publicly valid certificate. The practical choice when your directory uses a private or internal CA - this is what we use in this example.
Upload LDAP trusted certificate (optional): Click Choose File and upload your CA certificate (
.pemfile). Required when using LDAPS with a private or internal CA; otherwise you can skip it.
3. Click Save. The integration will appear in the Active Directories list above the screen.
Step 2: Fetch the Directory Structure
1. Click the domain's name (e.g., emu.local) from the list of Active Directories to reopen it.
2. Click Next: Fetch attributes. Teramind connects to your directory and reads its OUs, groups, and available attributes.
3. Scroll to the Import log at the bottom of the page to confirm the fetch succeeded. Verify the log entries: the OUs discovered in your directory, followed by Fetch is finished and ldap_tool is finished with the error code: 0 messages.
If the fetch fails, the problem is in the connection fields - recheck the server address, port, login, password, encryption method, and certificate, save, and try again.
Step 3: Finish Configuration and Run the Import
1. In Import users and computer from OUs (required for import), select the organizational units to import. Only users and computers in these OUs are brought into Teramind, and the OU structure becomes your Departments in the dashboard. In this example we selected seven OUs: Engineering, Contractors, Finance, Human Resources, Sales, Operations, and Marketing.
2. Choose your monitoring approach (optional) - one of the two:
a. Monitor only users in these groups: Select the groups whose members should be monitored (a whitelist). Only members of the selected groups are monitored. In this example we selected All Monitored, Design Managers, and Distributed COM Users.
b. Monitor all users, except for the ones in these groups: Select the groups to exclude (a blacklist). Everyone is monitored except members of the selected groups.
Use one monitoring approach, not both. Pick Monitor only users in these groups or Monitor all users, except for the ones in these groups and leave the other picker empty - combining them makes the resulting monitoring state hard to predict.
3. Set Update interval days (optional) - how often Teramind automatically re-syncs with the directory. 1 means a daily sync; higher numbers sync every N days.
4. Optionally, set Group to OU attribute (optional) - enter a single attribute name (for example, isDepartment). Groups that have this attribute set to TRUE in your directory are treated as OUs. Leave empty if your directory doesn't use this convention.
5. Review the remaining checkboxes (all optional):
Use domain name remapping: Allows remapping of a domain name in accordance with the rules.
Limit fetching (specify OUs and groups): Restricts the fetch to specific OUs and groups instead of reading the whole directory - useful for very large directories. When enabled, additional options appear:
Hierarchy: Fetch child OUs and groups only (respect hierarchy).
Fetch only these OUs (Organizational Units): Limit the fetch to the entered OUs (comma-separated names, e.g.,
ouNorthAmerica,ouAsia). If left empty, all OUs are fetched.Fetch only these groups: Limit the fetch to the entered groups (comma-separated names, e.g.,
grpSales,grpAdmin). If left empty, all groups are fetched.
Replicate computer's state: Replicates AD computer state with Teramind: AD-enabled computers are imported as auto-monitored; AD-disabled computers as non-monitored.
Do not monitor unavailable users: Disables monitoring of all computers that are not in the AD or out of the synced OU.
Disabling a user in Active Directory does not stop their monitoring. To stop monitoring an AD-synced user, either delete them in the AD or move them outside of any synced OUs - the Do not monitor unavailable users option then disables their monitoring on the next sync.
External sync script: Switches to the script-based approach - see Option 2: Script-Based Approach.
6. In Import attributes (optional), select the directory attributes to sync. Attributes bring directory information, such as names, email addresses, phone numbers, job title, etc. onto employee profiles in the Teramind Dashboard. The picker lists the attributes found in your directory during the fetch. In the example screenshot above, we selected givenName, sn, mail, telephoneNumber, and title as examples - your directory may offer these or others.
7. In Map imported attributes (optional), choose which of the attributes selected (in the Import attributes field) map to Employee Profile fields in the Teramind Dashboard. As you select attributes here, a mapping table appears below the field, where you assign each attribute to a profile field. Here’s a typical mapping, using the example attributes above:
AD Attribute (example) | Employee Profile field in Teramind |
| First Name |
| Last Name |
| |
| Phone |
| Position |
The attribute names in your directory may differ from the examples in the above table. Select whatever attributes your directory provides and map each one to the Employee Profile field you want it to populate. Mapping is optional: attributes selected in Import attributes but not mapped are still synced, and appear as key/value pairs on the employee profile's Attributes tab.
8. Click Save.
9. In the Active Directories list at the top of the page, click Next: Start Import on your integration's row.
10. Follow progress in the Import log. A successful import ends with Synchronization completed and Import is finished message, followed by ldap_tool is finished with the error code: 0.
Step 4: Verify the Results
Check the Employees page to confirm the imported users appear, and the Computers page to confirm the imported computers appear with the monitoring state your group selection implies. On the Configurations > Departments page, the imported OU structure appears as your departments. Then open any imported employee's profile in the dashboard and go to the Attributes tab: Identity Attributes shows the synced directory attributes as key/value pairs (for example, givenName: Abigail), and LDAP groups lists the employee's directory group memberships.
Step 5: Enable Domain Authentication (Optional/On-Premises Only)
This step applies to self-hosted (On-Premises/Private Cloud) deployments. On Teramind Cloud, dashboard sign-in supports password and SSO authentication; LDAP authentication is not offered.
The integration itself is complete - imported users, computers, and attributes sync on the schedule you set. As a follow-on on self-hosted deployments, you can let users sign in to the Teramind Dashboard with their Active Directory credentials:
1. From the Configurations > Settings > Authentication page, click Enable LDAP.
2. Click Save.
Before switching: the dashboard confirms authentication changes using the current method's credentials (the Changes confirmation setting on the same tab). Make sure at least one admin can confirm with a password before changing methods, or you can be locked out.
Option 2: Script-Based Approach
For advanced deployments, the integration can be configured as a JSON document instead of the standard form.
When to use which approach:
Use the script-based approach when you need custom sync logic the form can't express - and keep a downloaded copy of any working config before editing it.
To use the script-based approach, do the following:
1. From the Configurations > Settings > Active Directories page, click + Setup new integration.
2. Check External sync script. The standard form collapses: only Domain name remains, and the Import config JSON editor appears below it.
3. Enter your Domain name.
4. Write or paste your sync configuration in the Import config editor. The configuration should be in JSON format that defines the sync schedule and logic.
5. Use Upload config to load a previously exported configuration, or Download config to export the current one - useful for moving configurations between environments or keeping them under version control.
6. Click Save, then run the import (Option 1, Step 3, items 9-10) and verify the results (Option 1, Step 4).
Ongoing Synchronization
The integration re-syncs automatically every Update interval days (standard approach) or per the schedule in your import config (script-based approach).
To sync immediately - after changes in your directory or to the integration - click Next: Start Import anytime. Imports are re-runnable and update existing employee and computer records.
If your directory structure changes significantly (new OUs or attributes), click Next: Fetch attributes again to refresh the pickers before the next import.
Troubleshooting
The Import log at the bottom of the Active Directories page is the first place to look when something goes wrong - it records every fetch and import run, including what was synchronized, what was skipped, and any errors. A successful run ends with ldap_tool is finished with the error code: 0; a non-zero code or an error line points at the failing stage.
Symptom | What to check |
Fetch fails or OUs, attributes, groups, etc. fields don't show any selection list | Connection fields: server address, port, login, password, encryption method. For LDAPS with a private CA, confirm Accept specified or valid and the uploaded certificate. |
No users imported | Import users and computer from OUs - at least one OU must be selected. |
Identity Attributes empty/missing from employee profiles | Import attributes - select attributes, save, re-import. |
LDAP groups empty/missing from employee profiles | OU selection - groups outside the imported OUs don't sync. Re-import after adjusting. |
Import fails with | The |
Avoiding duplicate users when the domain changes: If the user is the same but the domain changes, use the TMDOMAINOVERRIDE Agent Installation/Configuration Parameter to keep the old domain. This won't fix duplicate users already on the Dashboard, but it prevents new ones. Note that Teramind doesn't allow two users with the same user@domain.