Common Mistakes

These are the most common issues we see during installation and configuration. Check this list first when troubleshooting.

1. SSL Inspection Breaking mTLS

Symptom: Connector connects but immediately disconnects, or certificate errors in logs.

Cause: Corporate firewall performing SSL inspection (MITM) on outbound connections.

Solution:

• Add api.adunlock.me to SSL inspection bypass list
• Connector uses mTLS which requires the original certificates to pass through

How to detect:

# Check certificate issuer
$webRequest = [Net.WebRequest]::Create("https://api.adunlock.me")
$webRequest.GetResponse() | Out-Null
$cert = $webRequest.ServicePoint.Certificate
Write-Host "Issuer: $($cert.Issuer)"
# Should be a public CA, NOT your company's internal CA

2. Hardcoding Password in Config File

Symptom: Works in testing, fails in production or password visible in logs.

Cause: Hardcoding service_password in config.yaml instead of environment variable.

Solution:

# config.yaml
 
# ❌ Wrong - password visible in file
ad:
  service_password: MySecretPassword123!
 
# ✅ Correct - password from environment
ad:
  service_password: ${AD_SERVICE_PASSWORD}

Then set via NSSM:

nssm set ADConnector AppEnvironmentExtra AD_SERVICE_PASSWORD=MySecretPassword123!

3. Wrong DN Syntax for Allowed OUs

Symptom: Users not found or “OU_NOT_ALLOWED” error.

Cause: Using wrong syntax for Distinguished Names.

Solution:

# config.yaml
 
# ❌ Wrong
allowed_ous:
  - "Users"
  - "company.local/Users"
 
# ✅ Correct
allowed_ous:
  - "OU=Users,DC=company,DC=local"
  - "OU=Employees,OU=Users,DC=company,DC=local"

How to find correct DN:

Get-ADOrganizationalUnit -Filter * | Select-Object DistinguishedName

4. Forgetting Denied Groups

Symptom: Domain Admin uses self-service to reset password, security incident.

Cause: Not configuring denied_groups to block privileged accounts.

Solution:

# config.yaml
ad:
  denied_groups:
    - "Domain Admins"
    - "Enterprise Admins"
    - "Schema Admins"
    - "Account Operators"
    - "Administrators"
    - "Backup Operators"

5. Using LDAP Instead of LDAPS

Symptom: Unlock works but password reset fails with “LDAP Error 53” or “unwilling to perform”.

Cause: Password operations require encrypted connection.

Solution:

# config.yaml
ad:
  port: 636
  tls_mode: ldaps  # Not "none" or blank

Or with StartTLS:

ad:
  port: 389
  tls_mode: starttls

6. Service Account Missing Permissions

Symptom: “Access Denied” errors in connector logs.

Cause: Service account doesn’t have delegated permissions on target OUs.

Solution: Re-run permissions script:

dsacls "OU=Users,DC=company,DC=local" /G "COMPANY\svc_adunlock:CA;Reset Password"
dsacls "OU=Users,DC=company,DC=local" /G "COMPANY\svc_adunlock:WP;lockoutTime"

Verify:

dsacls "OU=Users,DC=company,DC=local" | Select-String "svc_adunlock"

7. Wrong WhatsApp Number Format

Symptom: Users not found when sending messages.

Cause: Phone number format mismatch between enrollment and actual number.

Solution:

• Always use full international format: +5511999999999
• No spaces, dashes, or parentheses
• Include country code with +

8. Multiple Connectors with Different Configs

Symptom: Some operations work, some fail randomly.

Cause: Multiple connectors for same tenant have different AD configurations.

Solution: Ensure all connectors for same tenant have identical:

• allowed_ous
• denied_groups
• Service account permissions

9. Certificate Expiration

Symptom: Connector suddenly stops working after ~1 year.

Cause: mTLS certificates expire after 365 days.

How to check:

$cert = Get-PfxCertificate -FilePath "C:\ADConnector\certs\connector.pem"
Write-Host "Expires: $($cert.NotAfter)"

Solution:

1. Admin Portal → Connectors → [Your Connector] → Renew Certificate
2. Download new bundle
3. Replace certificates in C:\ADConnector\certs\
4. Restart service

10. Not Testing After Configuration Changes

Symptom: Changes made but users report issues.

Cause: No verification that changes work.

Solution: After any configuration change:

1. Restart connector service
2. Run verification script
3. Test with a real user (or test account)
4. Check logs for errors

# Quick verification
Restart-Service ADConnector
Start-Sleep 10
Get-Service ADConnector
Get-Content C:\ADConnector\logs\connector.log -Tail 20

11. Running Connector as Wrong User

Symptom: Connector can’t read certificates or config.

Cause: Service running as user without access to installation folder.

Solution:

# Check service account
Get-WmiObject Win32_Service -Filter "Name='ADConnector'" | Select-Object StartName
 
# Grant access to folder
$acl = Get-Acl "C:\ADConnector"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    "NT AUTHORITY\LOCAL SERVICE", "FullControl", "ContainerInherit,ObjectInherit", "None", "Allow"
)
$acl.AddAccessRule($rule)
Set-Acl "C:\ADConnector" $acl

12. Webhook Secret Not Configured

Symptom: WhatsApp messages not being processed.

Cause: Z-API webhook not sending correct secret or AD Unlock rejecting requests.

Solution:

1. In Admin Portal, go to Settings → WhatsApp
2. Copy the Webhook Secret
3. In Z-API dashboard, configure the secret in webhook settings
4. Test with Send Test Message

Quick Reference Card

Still Having Issues?