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