How AD Unlock Works

AD Unlock consists of three main components that work together to securely process self-service requests.

Architecture Overview


┌─────────────────────────────────────────────────────────────────────────┐
│                           YOUR NETWORK                                   │
│  ┌─────────────┐                                    ┌─────────────────┐ │
│  │   Active    │◄──── LDAPS (636) ────────────────►│   AD Connector  │ │
│  │  Directory  │                                    │  (Windows Svc)  │ │
│  └─────────────┘                                    └────────┬────────┘ │
│                                                              │          │
│                                                     WSS (443)│Outbound  │
│                                                              ▼          │
└──────────────────────────────────────────────────────────────┼──────────┘
                                                               │
┌──────────────────────────────────────────────────────────────┼──────────┐
│                        AD UNLOCK CLOUD                       │          │
│                                                              ▼          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────────────┐ │
│  │  WhatsApp   │───►│    API      │───►│       Connector Gateway     │ │
│  │   (Z-API)   │    │  (FastAPI)  │    │         (WebSocket)         │ │
│  └─────────────┘    └──────┬──────┘    └─────────────────────────────┘ │
│                            │                                            │
│                            ▼                                            │
│                    ┌─────────────┐                                      │
│                    │  PostgreSQL │ ◄── Row Level Security               │
│                    │    + Redis  │                                      │
│                    └─────────────┘                                      │
└─────────────────────────────────────────────────────────────────────────┘

Components

1. AD Connector (Your Network)

A lightweight Go executable that runs as a Windows Service in your network.

Responsibilities:

Maintains outbound WebSocket connection to Gateway
Executes LDAP operations against Active Directory
Encrypts passwords before transmission
Reports health status via heartbeats

Key characteristics:

No inbound ports required (outbound only)
mTLS authentication with certificates
Automatic reconnection if connection drops
Runs as Windows Service for reliability

2. Cloud API

FastAPI-based backend that handles all business logic.

Responsibilities:

Receives WhatsApp messages via webhook
Classifies intent using AI (Claude)
Manages user verification (OTP)
Evaluates risk and policies
Routes jobs to connectors

3. Connector Gateway

WebSocket server that maintains connections with all connectors.

Responsibilities:

Authenticates connector certificates (mTLS)
Routes jobs to correct connector
Handles reconnections gracefully
Provides real-time status

Request Flow

1. User Sends Message

User texts your WhatsApp Business number:

“My account is locked”

2. Intent Classification

Our AI (Claude) classifies the intent:

unlock - Account unlock request
reset_password - Password reset request
help - User needs assistance
other - Unrecognized request

3. User Lookup

System finds user by:

WhatsApp number in enrollment database
Matches to AD user (sAMAccountName, email, phone)

4. Identity Verification

System generates 6-digit OTP
Sends OTP to user’s registered email (not WhatsApp)
User replies with OTP code
System verifies (max 3 attempts, 5 min expiry)

5. Risk Assessment

System calculates risk score (0-100) based on:

Factor	Points
Outside business hours	+20
Weekend request	+15
Multiple requests today	+25
New WhatsApp number	+30
Failed OTP attempts	+10 each
Privileged group member	+50
Different city than usual	+20

6. Policy Evaluation

Policies determine the action:

Risk Score	Typical Action
0-30	Auto-approve
31-50	Auto-approve with alert
51-79	Require manual approval
80+	Block and alert security

7. Execution

If approved:

For Account Unlock:

Job sent to Connector via WebSocket
Connector sets lockoutTime = 0 via LDAP
Result returned to user via WhatsApp
Audit log created

For Password Reset:

Connector generates secure password
Password encrypted with RSA-OAEP (API’s public key)
Encrypted password sent to API
API sends password to user’s email only
User informed via WhatsApp to check email

Security Highlights

Passwords are NEVER sent via WhatsApp.

For password resets, a temporary password is generated by the connector and sent exclusively via email. WhatsApp only confirms the action was completed.

Zero Trust Architecture

Every request requires identity verification
Every operation is logged and auditable
No implicit trust, even for internal operations

mTLS Authentication

Connector uses client certificates
Certificate CN contains tenant_id and connector_id
Certificates signed by our CA
Invalid certificates rejected immediately

Password Protection

Passwords generated on connector (your network)
RSA-OAEP encryption before leaving your network
Decrypted only for email delivery
Never stored in database

Multi-Tenancy

Row Level Security (RLS) in PostgreSQL
Every query filtered by tenant_id
No cross-tenant data access possible

Sequence Diagram


User          WhatsApp       API            Gateway        Connector       AD
 │               │            │                │              │            │
 │──"locked"────►│            │                │              │            │
 │               │───webhook─►│                │              │            │
 │               │            │──lookup user──►│              │            │
 │               │            │◄──found────────│              │            │
 │               │            │                │              │            │
 │               │◄──OTP sent─│                │              │            │
 │               │            │                │              │            │
 │──"847291"────►│            │                │              │            │
 │               │───webhook─►│                │              │            │
 │               │            │──verify OTP───►│              │            │
 │               │            │◄──valid────────│              │            │
 │               │            │                │              │            │
 │               │            │──risk check────│              │            │
 │               │            │──policy check──│              │            │
 │               │            │                │              │            │
 │               │            │───unlock job──►│              │            │
 │               │            │                │──job────────►│            │
 │               │            │                │              │──LDAP─────►│
 │               │            │                │              │◄──OK───────│
 │               │            │                │◄─result──────│            │
 │               │            │◄───result──────│              │            │
 │               │            │                │              │            │
 │               │◄──unlocked─│                │              │            │
 │◄──"unlocked"──│            │                │              │            │

Next Steps

→ 5-Minute Tour → Requirements → Security Deep Dive