281 lines
9.4 KiB
Markdown
281 lines
9.4 KiB
Markdown
|
# MonacoUSA Portal - Integration Review & Troubleshooting Guide
|
||
|
|
|
||
|
|
## SMTP Email Integration Points
|
||
|
|
|
||
|
|
### 1. Email Configuration Storage
|
||
|
|
- **Location**: `server/utils/admin-config.ts`
|
||
|
|
- **Storage**: Encrypted in `/app/data/admin-config.json` (Docker) or `./data/admin-config.json` (local)
|
||
|
|
- **Fields**: host, port, secure, username, password, fromAddress, fromName
|
||
|
|
|
||
|
|
### 2. Email Service Implementation
|
||
|
|
- **Location**: `server/utils/email.ts`
|
||
|
|
- **Features**:
|
||
|
|
- Auto-detects security settings based on port
|
||
|
|
- Increased timeouts (60 seconds) for slow servers
|
||
|
|
- Supports STARTTLS (port 587) and SSL/TLS (port 465)
|
||
|
|
- Authentication type set to 'login' for compatibility
|
||
|
|
- Accepts self-signed certificates
|
||
|
|
|
||
|
|
### 3. Email Usage Points
|
||
|
|
- **Registration**: `server/api/registration.post.ts` - Sends welcome email with verification link
|
||
|
|
- **Portal Account Creation**: `server/api/members/[id]/create-portal-account.post.ts` - Sends welcome email
|
||
|
|
- **Password Reset**: `server/api/auth/forgot-password.post.ts` - Sends password reset link
|
||
|
|
- **Email Verification Resend**: `server/api/auth/send-verification-email.post.ts`
|
||
|
|
- **Test Email**: `server/api/admin/test-email.post.ts` - Admin panel test
|
||
|
|
|
||
|
|
### 4. Common SMTP Issues & Solutions
|
||
|
|
|
||
|
|
#### Issue: "500 plugin timeout" / EAUTH errors
|
||
|
|
**Solutions**:
|
||
|
|
1. **Port 587 (STARTTLS)**:
|
||
|
|
- Set SSL/TLS: OFF
|
||
|
|
- Username: Full email address (noreply@monacousa.org)
|
||
|
|
- Password: Your SMTP password (not email password if different)
|
||
|
|
|
||
|
|
2. **Port 465 (SSL/TLS)**:
|
||
|
|
- Set SSL/TLS: ON
|
||
|
|
- Same credentials as above
|
||
|
|
|
||
|
|
3. **Port 25 (Unencrypted)**:
|
||
|
|
- Set SSL/TLS: OFF
|
||
|
|
- May not require authentication
|
||
|
|
- Not recommended for production
|
||
|
|
|
||
|
|
4. **Alternative Configuration** for mail.monacousa.org:
|
||
|
|
- Try port 587 with SSL/TLS OFF
|
||
|
|
- Try port 465 with SSL/TLS ON
|
||
|
|
- Ensure username is full email address
|
||
|
|
- Some servers require app-specific passwords
|
||
|
|
|
||
|
|
#### Issue: Connection timeouts
|
||
|
|
**Solutions**:
|
||
|
|
- Timeouts already increased to 60 seconds
|
||
|
|
- Check firewall rules allow outbound connections on SMTP port
|
||
|
|
- Verify DNS resolution of mail server
|
||
|
|
|
||
|
|
#### Issue: Certificate errors
|
||
|
|
**Solutions**:
|
||
|
|
- Self-signed certificates are already accepted
|
||
|
|
- TLS minimum version set to TLSv1 for compatibility
|
||
|
|
|
||
|
|
### 5. Testing SMTP Without Email
|
||
|
|
If SMTP cannot be configured, the system gracefully handles email failures:
|
||
|
|
- Portal accounts are still created
|
||
|
|
- Users can use "Forgot Password" to set initial password
|
||
|
|
- Admin sees appropriate messages about email status
|
||
|
|
|
||
|
|
## Keycloak Integration Points
|
||
|
|
|
||
|
|
### 1. Authentication Flow
|
||
|
|
- **Login**: `server/api/auth/keycloak/login.get.ts` - Redirects to Keycloak
|
||
|
|
- **Callback**: `server/api/auth/keycloak/callback.get.ts` - Handles OAuth callback
|
||
|
|
- **Session**: `server/utils/session.ts` - Manages encrypted sessions
|
||
|
|
- **Logout**: `server/api/auth/logout.post.ts` - Clears session and Keycloak logout
|
||
|
|
|
||
|
|
### 2. User Management
|
||
|
|
- **Admin Client**: `server/utils/keycloak-admin.ts`
|
||
|
|
- **Features**:
|
||
|
|
- Create users with role-based registration
|
||
|
|
- Update user attributes (membership data)
|
||
|
|
- Password reset functionality
|
||
|
|
- Email verification tokens
|
||
|
|
- User search by email
|
||
|
|
|
||
|
|
### 3. Role-Based Access
|
||
|
|
- **Tiers**: admin, board, user
|
||
|
|
- **Middleware**:
|
||
|
|
- `middleware/auth.ts` - General authentication
|
||
|
|
- `middleware/auth-admin.ts` - Admin only
|
||
|
|
- `middleware/auth-board.ts` - Board and admin
|
||
|
|
- `middleware/auth-user.ts` - All authenticated users
|
||
|
|
|
||
|
|
### 4. Member-Portal Sync
|
||
|
|
- **Dual Database System**:
|
||
|
|
- NocoDB: Member records (source of truth)
|
||
|
|
- Keycloak: Authentication and portal accounts
|
||
|
|
- **Sync Points**:
|
||
|
|
- Registration creates both records
|
||
|
|
- Portal account creation links existing member to Keycloak
|
||
|
|
- Member updates sync to Keycloak attributes
|
||
|
|
|
||
|
|
### 5. Common Keycloak Issues & Solutions
|
||
|
|
|
||
|
|
#### Issue: Login redirect loops
|
||
|
|
**Solutions**:
|
||
|
|
- Check `NUXT_KEYCLOAK_CALLBACK_URL` matches actual domain
|
||
|
|
- Verify Keycloak client redirect URIs include callback URL
|
||
|
|
- Ensure session secret is set and consistent
|
||
|
|
|
||
|
|
#### Issue: User creation failures
|
||
|
|
**Solutions**:
|
||
|
|
- Check Keycloak admin credentials in environment
|
||
|
|
- Verify realm exists and is accessible
|
||
|
|
- Ensure email is unique in Keycloak
|
||
|
|
|
||
|
|
#### Issue: Role assignment not working
|
||
|
|
**Solutions**:
|
||
|
|
- Verify realm roles exist: user, board, admin
|
||
|
|
- Check client scope mappings include roles
|
||
|
|
- Ensure token includes role claims
|
||
|
|
|
||
|
|
## Environment Variables Required
|
||
|
|
|
||
|
|
### Keycloak Configuration
|
||
|
|
```env
|
||
|
|
NUXT_KEYCLOAK_ISSUER=https://auth.monacousa.org/realms/monacousa-portal
|
||
|
|
NUXT_KEYCLOAK_CLIENT_ID=monacousa-portal
|
||
|
|
NUXT_KEYCLOAK_CLIENT_SECRET=your-client-secret
|
||
|
|
NUXT_KEYCLOAK_CALLBACK_URL=https://monacousa.org/auth/callback
|
||
|
|
NUXT_KEYCLOAK_ADMIN_USERNAME=admin
|
||
|
|
NUXT_KEYCLOAK_ADMIN_PASSWORD=admin-password
|
||
|
|
```
|
||
|
|
|
||
|
|
### Session Security
|
||
|
|
```env
|
||
|
|
NUXT_SESSION_SECRET=48-character-secret-key
|
||
|
|
NUXT_ENCRYPTION_KEY=32-character-encryption-key
|
||
|
|
```
|
||
|
|
|
||
|
|
### Public Configuration
|
||
|
|
```env
|
||
|
|
NUXT_PUBLIC_DOMAIN=monacousa.org
|
||
|
|
```
|
||
|
|
|
||
|
|
## Health Check Endpoints
|
||
|
|
|
||
|
|
### System Health
|
||
|
|
- **Endpoint**: `GET /api/health`
|
||
|
|
- **Checks**:
|
||
|
|
- Database connectivity (NocoDB)
|
||
|
|
- Keycloak connectivity
|
||
|
|
- Session management
|
||
|
|
- File storage (if configured)
|
||
|
|
|
||
|
|
## Troubleshooting Workflow
|
||
|
|
|
||
|
|
### For SMTP Issues:
|
||
|
|
1. Try port 587 with SSL/TLS OFF first
|
||
|
|
2. If fails, try port 465 with SSL/TLS ON
|
||
|
|
3. Check credentials (use full email as username)
|
||
|
|
4. Test with personal Gmail/Outlook account to verify code works
|
||
|
|
5. Check firewall/network restrictions
|
||
|
|
6. Review server logs for specific error messages
|
||
|
|
|
||
|
|
### For Keycloak Issues:
|
||
|
|
1. Verify all environment variables are set
|
||
|
|
2. Check Keycloak server is accessible
|
||
|
|
3. Test with direct Keycloak login first
|
||
|
|
4. Review browser console for redirect issues
|
||
|
|
5. Check server logs for token/session errors
|
||
|
|
6. Verify realm and client configuration in Keycloak admin
|
||
|
|
|
||
|
|
## Manual SMTP Testing
|
||
|
|
|
||
|
|
To manually test SMTP settings without the portal:
|
||
|
|
|
||
|
|
### Using OpenSSL (for connection test):
|
||
|
|
```bash
|
||
|
|
# For STARTTLS (port 587)
|
||
|
|
openssl s_client -starttls smtp -connect mail.monacousa.org:587
|
||
|
|
|
||
|
|
# For SSL/TLS (port 465)
|
||
|
|
openssl s_client -connect mail.monacousa.org:465
|
||
|
|
```
|
||
|
|
|
||
|
|
### Using Telnet (for basic connectivity):
|
||
|
|
```bash
|
||
|
|
telnet mail.monacousa.org 587
|
||
|
|
```
|
||
|
|
|
||
|
|
### Using swaks (comprehensive SMTP test):
|
||
|
|
```bash
|
||
|
|
swaks --to test@example.com \
|
||
|
|
--from noreply@monacousa.org \
|
||
|
|
--server mail.monacousa.org:587 \
|
||
|
|
--auth LOGIN \
|
||
|
|
--auth-user noreply@monacousa.org \
|
||
|
|
--auth-password yourpassword \
|
||
|
|
--tls
|
||
|
|
```
|
||
|
|
|
||
|
|
## Alternative Email Solutions
|
||
|
|
|
||
|
|
If SMTP continues to fail:
|
||
|
|
|
||
|
|
### 1. Use Gmail with App Password:
|
||
|
|
- Enable 2FA on Gmail account
|
||
|
|
- Generate app-specific password
|
||
|
|
- Use smtp.gmail.com:587
|
||
|
|
- Username: your gmail address
|
||
|
|
- Password: app-specific password
|
||
|
|
|
||
|
|
### 2. Use SendGrid (Free tier available):
|
||
|
|
- Sign up at sendgrid.com
|
||
|
|
- Create API key
|
||
|
|
- Use smtp.sendgrid.net:587
|
||
|
|
- Username: apikey (literal string)
|
||
|
|
- Password: your API key
|
||
|
|
|
||
|
|
### 3. Use Local Mail Server (Development):
|
||
|
|
- Install MailHog or MailCatcher
|
||
|
|
- No authentication required
|
||
|
|
- Captures all emails locally
|
||
|
|
- Perfect for testing
|
||
|
|
|
||
|
|
## System Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
|
||
|
|
│ │────▶│ │────▶│ │
|
||
|
|
│ Frontend │ │ Nuxt API │ │ Keycloak │
|
||
|
|
│ (Vue/Vuetify) │◀────│ Routes │◀────│ Server │
|
||
|
|
│ │ │ │ │ │
|
||
|
|
└─────────────────┘ └──────────────┘ └─────────────┘
|
||
|
|
│ ▲
|
||
|
|
│ │
|
||
|
|
▼ │
|
||
|
|
┌──────────────┐ │
|
||
|
|
│ │ │
|
||
|
|
│ NocoDB │─────────────┘
|
||
|
|
│ Database │
|
||
|
|
│ │
|
||
|
|
└──────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌──────────────┐
|
||
|
|
│ │
|
||
|
|
│ SMTP │
|
||
|
|
│ Server │
|
||
|
|
│ │
|
||
|
|
└──────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
## Production Checklist
|
||
|
|
|
||
|
|
- [ ] All environment variables set correctly
|
||
|
|
- [ ] SSL certificates valid and configured
|
||
|
|
- [ ] Keycloak realm and client configured
|
||
|
|
- [ ] NocoDB database accessible and configured
|
||
|
|
- [ ] SMTP credentials tested and working
|
||
|
|
- [ ] Session secrets are strong and unique
|
||
|
|
- [ ] Firewall rules allow necessary ports
|
||
|
|
- [ ] Backup strategy in place
|
||
|
|
- [ ] Monitoring and logging configured
|
||
|
|
- [ ] Health check endpoint monitored
|
||
|
|
|
||
|
|
## Support Resources
|
||
|
|
|
||
|
|
- **Keycloak Documentation**: https://www.keycloak.org/documentation
|
||
|
|
- **NocoDB Documentation**: https://docs.nocodb.com
|
||
|
|
- **Nodemailer Documentation**: https://nodemailer.com
|
||
|
|
- **Nuxt 3 Documentation**: https://nuxt.com
|
||
|
|
|
||
|
|
## Contact for Issues
|
||
|
|
|
||
|
|
If you continue to experience issues after following this guide:
|
||
|
|
1. Check server logs for detailed error messages
|
||
|
|
2. Test each component independently
|
||
|
|
3. Verify network connectivity and DNS resolution
|
||
|
|
4. Review firewall and security group rules
|
||
|
|
5. Consider using alternative email providers
|