Active Directory Integration

Synchronize users from your on-premise Active Directory into Truetask. Accounts are pre-provisioned automatically — users can sign in immediately without manual setup.

Enterprise Feature

Active Directory integration requires an Enterprise license or an active trial period.

What It Does

• Pulls user accounts from AD and creates them in Truetask
• Lets you exclude specific OUs (service accounts, computers, etc.)
• Optionally promotes members of an AD admin group to the Truetask Admin role
• All other users receive the default User role
• Admins can adjust individual roles later from Settings > User Directory

Truetask never writes to Active Directory. All LDAP queries are read-only.

Prerequisites

Requirement	Details
AD Domain Services	Must be running on your domain controller
Service account	A dedicated AD account with read access to users and groups
Network access	Truetask server must reach the AD server on port 389 (LDAP) or 636 (LDAPS)
Firewall	Windows Firewall must allow inbound TCP on port 389/636

Setup

1. Verify Connectivity

From the Truetask server, confirm LDAP is reachable:

nc -zv <AD_SERVER_IP> 389

If the connection is refused, check on the domain controller:

# Verify AD DS is running
Get-Service NTDS

# Verify LDAP is listening
netstat -an | findstr ":389"

# Open firewall if needed
New-NetFirewallRule -DisplayName "LDAP" -Direction Inbound -Protocol TCP -LocalPort 389 -Action Allow

VPN / Network Routing

If connecting through a VPN, use the AD server's internal IP directly rather than a hostname that may resolve to multiple addresses.

2. Create a Service Account

In Active Directory Users and Computers, create a dedicated user for Truetask (e.g., svc-truetask) with:

• A strong password
• Password never expires enabled
• Read-only access to user and group objects (no admin permissions needed)

3. Configure in Truetask

Go to Settings > Server > Active Directory and enable the integration.

Connection

Field	Example
LDAP URL	ldap://10.0.10.14:389
Base DN	DC=company,DC=com
Bind DN	[email protected]
Bind Password	(service account password)

Click Test Connection to verify before proceeding.

Email Attribute

Choose which AD attribute becomes the user's email in Truetask:

Attribute	When to use
userPrincipalName	Most common ([email protected] format). Use this if your users don't have the mail field populated.
mail	Use if your organization populates the email field in AD.

Organizational Units

Click Discover OUs to see where your users are located. Uncheck any OUs you want to exclude from the sync — typically service accounts, computer accounts, or test users.

Admin Promotion (Optional)

Enable Promote AD admins to automatically assign the Admin role to members of specific AD groups. Click Discover Groups and select the relevant groups (e.g., Admin, IT-Admins).

All other synced users receive the default User role.

4. Save and Sync

1. Click Save to store the configuration
2. Click Preview to see which users would be created (no changes are made)
3. Review the list, then click Sync Now to create the accounts

How Sync Works

Scenario	What happens
New user in AD	Truetask account created with name, email, and role
Existing user, role unchanged	Skipped (no changes)
Existing user, now in admin group	Role upgraded to Admin
User removed from AD	Nothing — existing accounts are preserved

• Accounts are created as verified — no email confirmation required
• Accounts receive a random password (users authenticate via SSO/OAuth or password reset)
• Role upgrades only — the sync never downgrades an existing Owner or Admin

Security

• Use LDAPS (port 636) in production for encrypted communication
• Enable database encryption (PB_ENCRYPTION_KEY) to encrypt the stored bind password
• The service account should have read-only access — never use a Domain Admin account
• All sync events are recorded in the Audit Log

Troubleshooting

Connection refused

• Verify AD DS is running (Get-Service NTDS)
• Check LDAP is listening (netstat -an | findstr ":389")
• Add firewall rules for TCP 389/636

Invalid credentials

• Try both formats: [email protected] and CN=user,CN=Users,DC=domain,DC=com
• Verify the account isn't locked or disabled

No users found

• Check the Base DN covers the container where users reside (often CN=Users,DC=...)
• If users lack the mail attribute, switch to userPrincipalName
• Verify excluded OUs aren't filtering out the users you expect

Users created but can't sign in

• Pre-provisioned accounts have random passwords
• Users should authenticate via your configured OAuth/SSO provider or use the password reset flow