Authentication & Security
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication & Security system provides a robust, multi-layered defense mechanism designed to protect the marketing automation platform and its multi-tenant data. It encompasses user identity verification, granular access control, data encryption, and audit tracking to ensure compliance with enterprise standards and regulatory requirements like GDPR.
The system is built on a modern security stack, primarily utilizing Clerk for identity management and JWT-based authentication for API security. It follows the TRUST 5 quality framework, ensuring the codebase is Secured through OWASP compliance, input validation, and rate limiting.
Sources: README.md, moai-project.yaml, CHANGELOG.md:Unreleased
Identity and Access Management (IAM)
The core of the security infrastructure is the Identity and Access Management layer, which handles user lifecycle from registration to session termination.
User Authentication
The system supports multiple authentication methods to accommodate different user needs, including standard email/password, magic links, and Single Sign-On (SSO) via SAML or OAuth. Session management is handled through JWT (JSON Web Tokens) with a specific lifecycle configuration: an access token TTL of 15 minutes and a refresh token TTL of 7 days.
Sources: specs/whitelabel/security.yaml:SPEC-SEC-001, FINAL_REPORT.md:Testing
Multi-Factor Authentication (MFA)
To enhance account security, Two-Factor Authentication (2FA) is implemented as a high-priority feature. Users can verify their identity using TOTP apps, SMS codes, email codes, or backup codes in case of primary factor loss.
Sources: specs/whitelabel/security.yaml:SPEC-SEC-002, moai-project.yaml:auth
Role-Based Access Control (RBAC)
Access to various platform modules is governed by a hierarchical Role-Based Access Control system. Permissions are categorized by domain (e.g., contacts, campaigns, funnels, billing) and assigned to specific roles.
| Role | Description |
|---|---|
| Super Admin | Full system-wide access across all accounts. |
| Agency Admin | Management access for a specific agency and its sub-accounts. |
| Agency User | Standard access to agency tools and assigned sub-accounts. |
| Account Admin | Full management access within a single sub-account. |
| Account User | Standard operational access within a sub-account. |
| Custom Role | User-defined roles with specific permission sets. |
Sources: specs/whitelabel/security.yaml:SPEC-SEC-003
Authentication Flow Diagram
The following sequence diagram illustrates the standard JWT authentication and authorization flow.
Multi-Tenancy and Data Isolation
Data isolation is a critical security requirement for this platform, ensuring that data from one account is never accessible to another.
Row-Level Security (RLS)
The backend enforces account-scoped data isolation through middleware that extracts the account_id from the authenticated JWT context. This ID is used to filter all database queries automatically, preventing cross-tenant access.
Sources: README.md:Key Highlights, FINAL_REPORT.md:Security Measures
Resource Protection
The system implements rate limiting to prevent abuse and ensure service availability. Using a Redis-backed distributed rate limiter, the system restricts accounts to 100 requests per hour by default, returning a 429 Too Many Requests status when exceeded.
Sources: CHANGELOG.md:Unreleased, specs/whitelabel/security.yaml:SPEC-SEC-004
Data Protection and Encryption
Sensitive information is protected at rest and in transit using industry-standard cryptographic protocols.
Encryption Standards
The system employs AES-256 for data at rest, managed via AWS KMS (Key Management Service). Data in transit is secured using TLS 1.3 with auto-managed certificates.
| Field Type | Protection Method |
|---|---|
| Passwords | BCrypt Hashing |
| API Keys | AES-256 Encryption |
| Payment Info | Tokenization (Stripe) |
| Personal Data | Encrypted at Rest |
Sources: specs/whitelabel/security.yaml:SPEC-SEC-005, FINAL_REPORT.md:Infrastructure
Webhook Security
Outgoing webhooks are signed using HMAC-SHA256 with a signature header (X-Signature) and timestamp validation to prevent replay attacks. Incoming webhooks undergo signature verification and optional IP whitelisting.
Sources: specs/whitelabel/security.yaml:SPEC-SEC-010, FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:Security Implementation
Threat Protection and Compliance
The platform is designed to defend against common web vulnerabilities and comply with global data privacy regulations.
OWASP Top 10 Protections
The implementation architecture specifically addresses common threats identified by OWASP:
- SQL Injection: Prevented through the use of SQLAlchemy's parameterized queries.
- XSS (Cross-Site Scripting): Mitigated by React's automatic output encoding.
- CSRF (Cross-Site Request Forgery): Protected via token validation for mutations.
- Brute Force: Mitigated through account lockout policies (after 10 failed attempts) and CAPTCHA triggers (after 3 failed attempts).
Sources: specs/whitelabel/security.yaml:SPEC-SEC-007, specs/whitelabel/security.yaml:SPEC-SEC-009, FINAL_REPORT.md:Security Measures
Audit Logging
Significant security events are recorded in an immutable audit trail. Logged actions include login attempts, permission changes, data exports, and API key operations. These logs are retained for 2 years to facilitate compliance auditing.
Sources: specs/whitelabel/security.yaml:SPEC-SEC-006, CHANGELOG.md:Unreleased
GDPR Compliance
The platform includes built-in features for GDPR compliance, such as consent management, data export in JSON format, and a "right to erasure" through data deletion protocols.
Sources: specs/whitelabel/security.yaml:SPEC-SEC-008
Conclusion
The Authentication & Security system is a comprehensive framework that integrates identity management, multi-tenant isolation, and proactive threat protection. By leveraging industry-standard tools like Clerk, JWT, and AES-256, alongside strict DDD-based multi-tenancy enforcement, the project ensures that user data remains confidential and the system remains resilient against attacks.
Sources: FINAL_REPORT.md:Calidad y Seguridad, DOCUMENTATION_SUMMARY.md:Architecture Documentation