Security Architecture
Network Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ CUSTOMER NETWORK │
│ │
│ ┌─────────────────┐ ┌────────────────────────────────────┐ │
│ │ Active │ │ AD Connector │ │
│ │ Directory │◄── LDAPS ─►│ ┌─────────────────────────────┐ │ │
│ │ │ (636) │ │ • mTLS Client Cert │ │ │
│ │ • Users │ │ │ • RSA Key for Passwords │ │ │
│ │ • Groups │ │ │ • Config Encryption │ │ │
│ │ • Policies │ │ └─────────────────────────────┘ │ │
│ └─────────────────┘ └───────────────┬────────────────────┘ │
│ │ │
│ │ WSS/443 (Outbound) │
│ │ mTLS │
└─────────────────────────────────────────────────┼────────────────────────┘
│
┌─────────────────────────────────────────────────┼────────────────────────┐
│ AD UNLOCK CLOUD ▼ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ WhatsApp │────►│ API │────►│ Connector Gateway │ │
│ │ (Z-API) │ │ (FastAPI) │ │ (WebSocket + mTLS) │ │
│ └──────────────┘ └──────┬───────┘ └──────────────────────────┘ │
│ │ │
│ ┌──────────────┐ ┌──────▼───────┐ ┌──────────────────────────┐ │
│ │ Email │◄────│ PostgreSQL │────►│ Redis │ │
│ │ (Password) │ │ (RLS) │ │ (Streams) │ │
│ └──────────────┘ └──────────────┘ └──────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘Authentication Flow
Admin Portal
- User clicks “Sign In”
- Redirected to Azure AD / Google
- OAuth2 authorization code flow
- JWT tokens stored securely
- API calls include Bearer token
Connector
- Connector loads client certificate
- Establishes WebSocket with mTLS
- Gateway validates certificate chain
- Extracts tenant_id and connector_id from CN
- Maintains authenticated session
WhatsApp User
- User sends message
- Webhook validates secret
- System looks up user by phone
- OTP sent to registered email
- User verifies with OTP code
Data Flow
Account Unlock
1. User: "unlock my account" via WhatsApp
2. API: Classify intent (Claude AI)
3. API: Lookup user by phone number
4. API: Generate OTP, send to email
5. User: Reply with OTP
6. API: Verify OTP, calculate risk score
7. API: Check policies
8. API: Create unlock job
9. Gateway: Route to connector
10. Connector: Execute LDAP unlock
11. Connector: Return result
12. API: Notify user via WhatsApp
13. API: Create audit log entryPassword Reset
1-8. Same as unlock
9. Gateway: Route to connector
10. Connector: Generate secure password
11. Connector: Encrypt with API's public key
12. Connector: Execute LDAP password change
13. Connector: Return encrypted password
14. API: Decrypt password
15. API: Send password via EMAIL (not WhatsApp)
16. API: Notify user to check email
17. API: Securely delete password from memory
18. API: Create audit log entryEncryption
In Transit
| Connection | Protocol |
|---|---|
| Admin Portal → API | TLS 1.3 |
| WhatsApp → API | TLS 1.3 |
| Connector → Gateway | TLS 1.3 + mTLS |
| Connector → AD | LDAPS (TLS 1.2+) |
At Rest
| Data | Encryption |
|---|---|
| Database | AES-256 (transparent) |
| Secrets | AWS Secrets Manager |
| Passwords | Never stored |
| Audit Logs | Immutable, checksummed |
Password Handling
- Generated on connector (customer network)
- Encrypted with RSA-OAEP (2048-bit)
- Transmitted encrypted
- Decrypted only for email
- Immediately zeroed from memory
- Never logged or stored
Last updated on