Installation Steps

⏱️10 minutes

Download, configure, and run the connector.

Prerequisite: Complete Before You Install first.

Step 1: Create Connector in Portal

Log in to admin.adunlock.me
Go to Connectors → Create Connector
Enter a name (e.g., “DC01-CONNECTOR”)
Click Create
Download Bundle (contains certificates and config template)

✅Expected Result

Downloaded file: connector-bundle.zip

Step 2: Extract Bundle


# Extract to installation directory
Expand-Archive -Path connector-bundle.zip -DestinationPath C:\ADConnector -Force
 
# Verify contents
Get-ChildItem C:\ADConnector

✅Expected Result


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----           1/15/2024  10:30 AM                certs
-a---           1/15/2024  10:30 AM         123456 connector.exe
-a---           1/15/2024  10:30 AM           1234 config.yaml.example

Step 3: Configure

Copy and edit the configuration file:


Copy-Item C:\ADConnector\config.yaml.example C:\ADConnector\config.yaml
notepad C:\ADConnector\config.yaml

Configuration File


# C:\ADConnector\config.yaml
 
# Gateway connection (don't change)
gateway:
  url: wss://api.adunlock.me/ws
  tenant_id: "YOUR_TENANT_ID"       # From Admin Portal
  connector_id: "YOUR_CONNECTOR_ID" # From Admin Portal
 
# mTLS certificates (don't change paths unless needed)
tls:
  cert_file: "certs/connector.pem"
  key_file: "certs/connector-key.pem"
  ca_file: "certs/ca.pem"
 
# Active Directory connection
ad:
  server: "dc01.company.local"      # Your DC FQDN
  port: 636
  tls_mode: "ldaps"                 # or "starttls"
 
  # Service account
  service_account: "svc_adunlock@company.local"
  service_password: "${AD_SERVICE_PASSWORD}"  # From environment
 
  # Search settings
  base_dn: "DC=company,DC=local"
 
  # Allowed OUs (only users in these OUs can use self-service)
  allowed_ous:
    - "OU=Staff,OU=Users,DC=company,DC=local"
    - "OU=Remote,OU=Users,DC=company,DC=local"
 
  # Denied groups (members cannot use self-service)
  denied_groups:
    - "Domain Admins"
    - "Enterprise Admins"
    - "Schema Admins"
    - "Account Operators"
 
# Logging
logging:
  level: "info"
  file: "logs/connector.log"
  max_size_mb: 10
  max_backups: 5

Never hardcode passwords in config.yaml. Use environment variables.

Step 4: Set Password Environment Variable


# Set environment variable for current session (for testing)
$env:AD_SERVICE_PASSWORD = "YourSecurePassword123!"
 
# For production, set system-wide (requires restart or new session)
[Environment]::SetEnvironmentVariable(
    "AD_SERVICE_PASSWORD",
    "YourSecurePassword123!",
    "Machine"
)

Step 5: Test Run

Run the connector manually to verify:


cd C:\ADConnector
.\connector.exe --config config.yaml

✅Expected Result


{"level":"info","message":"AD Connector starting","version":"1.0.0"}
{"level":"info","message":"configuration loaded"}
{"level":"info","message":"LDAP connectivity verified","server":"dc01.company.local"}
{"level":"info","message":"connecting to gateway"}
{"level":"info","message":"connected to gateway","url":"wss://api.adunlock.me/ws"}
{"level":"info","message":"heartbeat sent"}

Press Ctrl+C to stop after verifying it connects.

🔧If Something Goes Wrong

Symptom	Cause	Solution
connection refused to gateway	Firewall blocking outbound 443	Allow outbound HTTPS to api.adunlock.me
certificate signed by unknown authority	SSL inspection active	Add exception for api.adunlock.me
LDAP bind failed	Wrong credentials or DC unreachable	Verify service account UPN and password
config file not found	Working directory wrong	Run from C:\ADConnector directory

Troubleshooting Commands

Check Gateway Connectivity


Test-NetConnection -ComputerName api.adunlock.me -Port 443

Check LDAP Connectivity


Test-NetConnection -ComputerName dc01.company.local -Port 636

Test LDAP Bind


# Requires RSAT AD PowerShell module
$cred = Get-Credential -UserName "svc_adunlock@company.local"
Get-ADUser -Identity "svc_adunlock" -Server "dc01.company.local" -Credential $cred

Next Step

→ Verification