# Keycloak vs Basic Authentication

> Compare Basic Authentication with Keycloak integration to understand the benefits and migration path for Edesy Email.

Source: https://edesy.in/docs/email-platform/advanced/keycloak-vs-basic-auth

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

## Quick Comparison

| Feature | Basic Auth | Keycloak |
|---------|-----------|----------|
| **Users** | Single user only | Unlimited users |
| **User Management** | Environment variables | Web UI + API |
| **Multi-Factor Auth** | No | Yes (built-in) |
| **Single Sign-On** | No | Yes |
| **Social Login** | No | Yes (Google, GitHub, etc.) |
| **LDAP/AD Integration** | No | Yes |
| **Password Policies** | No | Yes (customizable) |
| **Audit Logs** | Limited | Full audit trail |
| **Session Management** | Basic | Advanced |
| **Role-Based Access** | No | Yes |
| **Account Recovery** | No | Yes |
| **Account Lockout** | No | Yes |
| **Unified Login** | No | Yes (across apps) |
| **Setup Complexity** | Very Easy | Moderate |
| **Maintenance** | Minimal | Regular updates |
| **Scalability** | Limited | Enterprise-grade |
| **Best For** | Evaluation/Demo | Production use |

## Current Setup (Basic Auth)

### Configuration

```bash
# .env file
AUTH_DRIVER=basic
AUTH_BASIC_EMAIL=test@edesy-email.com
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

```bash
# .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:

```bash
# Keep both enabled during testing
AUTH_DRIVER=basic,openid

# Basic auth config (existing)
AUTH_BASIC_EMAIL=test@edesy-email.com
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:

```bash
# 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 user1@mycompany.com
2. Visit crm.mycompany.com -> Login AGAIN with user1@mycompany.com
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:
+-- user1@mycompany.com (Admin)
+-- user2@mycompany.com (User)
+-- user3@mycompany.com (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](https://edesy.in/docs/email-platform/advanced/keycloak-integration)

## 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