Security & 2FA

Security Best Practices

The KW Group platform is designed with security as a baseline. This article covers the security features available and how to configure them.

Two-Factor Authentication (2FA)

2FA adds a second verification step after password login, significantly reducing the risk of account takeover.

Enforcing 2FA Organisation-Wide

1. Go to Admin → Security → 2FA Policy.
2. Choose the enforcement level:
   • Optional — users can enable it themselves, not required.
   • Required for Admins — ADMIN and SUPER_ADMIN must use 2FA.
   • Required for All — every user must set up 2FA before their next login.
3. Click Save.

When enforcement is raised, users without 2FA configured are redirected to set it up on their next login. VENDOR users are exempted from enforcement by default — vendors log in to a separate portal at /vendor-login and 2FA-enforcing them tends to break their one-off session flow. Re-enable per-vendor from the user profile if needed.

Supported 2FA Methods

• TOTP (Time-based One-Time Password) — works with Google Authenticator, Authy, Microsoft Authenticator, 1Password, and any RFC 6238-compliant app.

The platform does not currently issue printable recovery / backup codes. If a user loses their authenticator app, a SUPER_ADMIN must reset 2FA on their account from Admin → Users → [User] → Reset 2FA. This is intentional — TOTP secrets never leave the database in a recoverable form, so there is nothing to back up.

Audit Log

Every significant action in the platform is recorded in the audit log: logins, ticket changes, user management, settings changes, API calls.

1. Go to Admin → Audit Log.
2. Filter by user, resource type, action, date range, or IP address.
3. Export to CSV for compliance reporting.

Audit log entries are immutable and cannot be deleted by any user, including SUPER_ADMIN.

Session Management

1. Go to Admin → Security → Session Policy.
2. Configure:
   • Access Token Expiry — default 15 minutes.
   • Refresh Token Expiry — default 30 days.
   • Max Concurrent Sessions — limit how many devices a user can be logged in on simultaneously.

Users can view and revoke their own active sessions from Profile → Active Sessions.

API Security

• All API calls require a JWT token or service key.
• The SERVICE_SECRET in each microservice's configuration must be changed from the default change-me-service-secret in any production deployment.
• Rotate the JWT_SECRET and SERVICE_SECRET values if you suspect a breach.

Data Encryption

• Passwords are stored as bcrypt hashes (cost factor 10).
• 2FA secrets are stored encrypted at rest.
• Vault secrets are encrypted using the Vaultwarden encryption layer before storage.
• Files in MinIO are stored with server-side encryption if configured on the MinIO instance.

Network Security

• The platform is designed to run behind a Traefik reverse proxy that handles TLS termination.
• All communication between microservices should be on a private network (Docker internal network or VPN).
• Expose only ports 80 and 443 publicly; all microservice ports (3001-3020) must not be publicly reachable.
• Ensure SPF, DKIM, and DMARC records are configured for your sending domain to prevent email spoofing.