Keycloak vs Basic Authentication

This guide compares Basic Authentication (default) with Keycloak integration to help you understand the benefits and migration path.

Quick Comparison#

Current Setup (Basic Auth)#

Configuration#

# .env file
AUTH_DRIVER=basic
[email protected]
AUTH_BASIC_PASSWORD=password
AUTH_BASIC_NAME=Login

How It Works#

+----------+
|  User    |
+----+-----+
     | 1. Enter email/password
     v
+--------------+
|  Edesy Email | 2. Check against ENV vars
|              | 3. Login if match
+--------------+

Limitations#

• Only one user can log in
• To add users, need to modify env vars and restart
• No password reset capability
• No security features (MFA, account lockout, etc.)
• Can't integrate with existing identity systems
• No unified login across multiple apps

With Keycloak#

Configuration#

# .env file
AUTH_DRIVER=openid
AUTH_OPENID_NAME=Login with Keycloak
AUTH_OPENID_ISSUER_URL=https://auth.mycompany.com/realms/production
AUTH_OPENID_CLIENT_ID=edesy-email
AUTH_OPENID_CLIENT_SECRET=secret-from-keycloak
AUTH_OPENID_DOMAIN=mycompany.com  # Optional: restrict domains

How It Works#

+----------+
|  User    |
+----+-----+
     | 1. Click "Login with Keycloak"
     v
+--------------+
|  Edesy Email | 2. Redirect to Keycloak
+--------------+
     v
+--------------+
|  Keycloak    | 3. User enters credentials
|              | 4. Authenticate (+ MFA if enabled)
+--------------+
     | 5. Redirect back with token
     v
+--------------+
|  Edesy Email | 6. Validate token
|              | 7. Create session
+--------------+

Benefits#

• Unlimited users
• Centralized user management
• Add/remove users without restarting
• Built-in security features
• Integrates with existing systems
• Unified login across all your apps
• Professional authentication experience

Migration Path#

Phase 1: Setup (No Downtime)#

Keep basic auth running while you set up Keycloak:

# Keep both enabled during testing
AUTH_DRIVER=basic,openid

# Basic auth config (existing)
[email protected]
AUTH_BASIC_PASSWORD=password
AUTH_BASIC_NAME=Login

# Add Keycloak config
AUTH_OPENID_NAME=Login with Keycloak
AUTH_OPENID_ISSUER_URL=https://your-keycloak.com/realms/your-realm
AUTH_OPENID_CLIENT_ID=edesy-email
AUTH_OPENID_CLIENT_SECRET=your-secret

Result: Users will see two login options:

• "Login" (basic auth)
• "Login with Keycloak" (new)

Phase 2: Testing#

1. Create your admin account in Keycloak with the same email
2. Test logging in via Keycloak
3. Verify all features work correctly
4. Keep basic auth as backup

Phase 3: Full Migration#

Once you're confident Keycloak works:

# Remove basic auth
AUTH_DRIVER=openid

# Only Keycloak config remains
AUTH_OPENID_NAME=Login with Keycloak
AUTH_OPENID_ISSUER_URL=https://your-keycloak.com/realms/your-realm
AUTH_OPENID_CLIENT_ID=edesy-email
AUTH_OPENID_CLIENT_SECRET=your-secret
AUTH_OPENID_DOMAIN=  # Optional

Result: All users must authenticate via Keycloak

Real-World Example: Zoho-Style Unified Login#

Your Company Setup#

Let's say you have multiple applications:

1. Edesy Email (email platform) - email.mycompany.com
2. CRM application - crm.mycompany.com
3. Project management - projects.mycompany.com
4. Analytics dashboard - analytics.mycompany.com

Without Keycloak#

User Journey (Painful):

1. Visit email.mycompany.com -> Login with [email protected]
2. Visit crm.mycompany.com -> Login AGAIN with [email protected]
3. Visit projects.mycompany.com -> Login AGAIN...
4. Visit analytics.mycompany.com -> Login AGAIN...

- 4 separate logins
- 4 different password reset flows
- 4 places to manage users
- Inconsistent security policies

With Keycloak#

User Journey (Smooth):

1. Visit email.mycompany.com -> Redirect to Keycloak
2. Login once at auth.mycompany.com (with MFA if enabled)
3. Redirected back to email.mycompany.com -> Logged in
4. Visit crm.mycompany.com -> Automatically logged in
5. Visit projects.mycompany.com -> Automatically logged in
6. Visit analytics.mycompany.com -> Automatically logged in

+ 1 login for all apps
+ 1 password reset flow
+ 1 place to manage users
+ Consistent security policies
+ Professional authentication experience

Keycloak Configuration#

Keycloak Realm: "mycompany"

Users:
+-- [email protected] (Admin)
+-- [email protected] (User)
+-- [email protected] (User)
+-- ...

Clients:
+-- edesy-email
|   +-- Client ID: edesy-email
|   +-- Redirect URI: https://email.mycompany.com/api/auth/login/openid/callback
|   +-- Scopes: openid, email, profile
+-- crm
|   +-- Client ID: crm
|   +-- Redirect URI: https://crm.mycompany.com/auth/callback
|   +-- Scopes: openid, email, profile
+-- projects
|   +-- Client ID: projects
|   +-- Redirect URI: https://projects.mycompany.com/oauth/callback
|   +-- Scopes: openid, email, profile
+-- analytics
    +-- Client ID: analytics
    +-- Redirect URI: https://analytics.mycompany.com/login/callback
    +-- Scopes: openid, email, profile

When to Use Each#

Use Basic Auth When:#

• You're evaluating Edesy Email
• Local development/testing
• Single user is sufficient
• Quick demo/proof of concept
• Temporary installation

Use Keycloak When:#

• Production deployment
• Multiple team members need access
• You want professional security
• You need unified login across apps
• Compliance requirements (audit logs, MFA, etc.)
• Integration with existing identity systems
• Growing team

Cost Comparison#

Basic Auth#

• Setup Time: 2 minutes
• Maintenance: None
• Infrastructure: None (built into Edesy Email)
• Total Cost: $0
• User Capacity: 1 user

Keycloak#

• Setup Time: 30-60 minutes (initial)
• Maintenance: ~1 hour/month (updates, monitoring)
• Infrastructure:
  • Self-hosted: ~$10-20/month (small VM)
  • Managed Keycloak: ~$50-200/month
• Total Cost: $10-200/month
• User Capacity: Unlimited

ROI Consideration: If you have even 2+ users or multiple applications, Keycloak pays for itself in saved time and improved security.

Security Comparison#

Basic Auth Security#

Threats:
- Credentials in environment variables (visible to anyone with server access)
- No rate limiting on login attempts
- No account lockout after failed attempts
- No password complexity requirements
- No password expiration
- No audit trail of login attempts
- No MFA protection
- Password changes require server restart

Keycloak Security#

Protections:
+ Credentials never in environment variables
+ Rate limiting built-in
+ Account lockout after failed attempts
+ Configurable password policies
+ Optional password expiration
+ Complete audit trail
+ MFA/2FA support (TOTP, WebAuthn, SMS)
+ Instant password changes
+ Session management
+ Brute force detection
+ HTTPS enforced
+ OAuth2/OIDC security standards

Performance Impact#

Basic Auth#

• Login Time: < 100ms (local check)
• Memory: Negligible
• Network: None (no external calls)

Keycloak#

• Login Time: 200-500ms (redirect + token exchange)
• Memory: Negligible (after initial login)
• Network: 2-3 HTTP requests during login
• Subsequent Logins: < 100ms (token validation)

Note: The slight increase in login time is negligible compared to the security and features gained.

User Experience Comparison#

Basic Auth UX#

Login Screen:
+----------------------+
|  Email:              |
|  [input field]       |
|                      |
|  Password:           |
|  [input field]       |
|                      |
|  [Login Button]      |
+----------------------+

Issues:
- Forgot password? Contact admin
- Need MFA? Not supported
- Wrong credentials? Try again (no feedback)

Keycloak UX#

Login Screen:
+----------------------+
|  [Login with         |
|   Keycloak]          |
+----------------------+
         |
Redirect to Keycloak:
+----------------------+
|  Company Login       |
|                      |
|  Email:              |
|  [input field]       |
|                      |
|  Password:           |
|  [input field]       |
|                      |
|  [Login Button]      |
|                      |
|  Forgot password?    |
|  Register            |
+----------------------+
         |
If MFA enabled:
+----------------------+
|  Enter Code:         |
|  [input field]       |
|  [Verify Button]     |
+----------------------+
         |
Back to Edesy Email

Features:
- Forgot password? Self-service reset
- Need MFA? Built-in support
- Wrong credentials? Clear feedback + lockout protection
- Professional branded login page

Conclusion#

For Evaluation/Testing#

Use Basic Auth - It's simple, quick, and perfect for trying out Edesy Email.

For Production#

Use Keycloak - The investment pays off in:

• Better security
• Professional user experience
• Time saved on user management
• Unified authentication across apps
• Compliance and audit capabilities

Best Practice#

Start with Basic Auth during evaluation, then migrate to Keycloak before going to production. The migration is straightforward and can be done with zero downtime.

Next Steps#

1. Review this comparison
2. Decide which auth method fits your needs
3. If choosing Keycloak, follow the Full Integration Guide

Questions?#

• "I'm just testing Edesy Email" -> Use Basic Auth
• "I need to add team members" -> Use Keycloak
• "I want unified login across apps" -> Use Keycloak
• "I need enterprise security" -> Use Keycloak
• "I'm deploying to production" -> Use Keycloak
• "Budget is extremely tight" -> Start with Basic, plan for Keycloak
• "I need it working in 5 minutes" -> Basic Auth now, Keycloak later