matt
/
monacousa-portal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
monacousa-portal/docs-archive/INTEGRATION_REVIEW.md

9.4 KiB
Raw Blame History

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

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

NUXT_SESSION_SECRET=48-character-secret-key
NUXT_ENCRYPTION_KEY=32-character-encryption-key

Public Configuration

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):

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

telnet mail.monacousa.org 587

Using swaks (comprehensive SMTP test):

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

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