Authentication

The Ellemment Stack provides robust authentication using web standards and established libraries. The authentication system is designed to be both secure and flexible, offering multiple authentication mechanisms out of the box.

Authentication Methods

The stack offers two primary mechanisms for authentication:

1. Username and password authentication
2. Provider authentication (SSO)

Email-Password Authentication Process

When a user wishes to sign up for an account, they go through a secure verification process:

Initial Signup

1. Users provide their email address through the signup form
2. The system generates:
   • A verification code using TOTP (Time-based One Time Password)
   • A secure magic link

Email Verification

The system sends an email containing:

• The generated verification code
• The magic link
• Instructions for both verification methods

Users can verify their email through either:

• Entering the verification code on the verification page
• Clicking the magic link in their email

Account Setup

After successful verification, users complete the onboarding flow by:

1. Setting their username
2. Creating a secure password
3. Optionally enabling additional security features

The password is securely hashed using the bcrypt algorithm with appropriate salt rounds for maximum security.

Provider Authentication (SSO)

The stack includes a comprehensive system for third-party authentication, built using remix-auth. This enables easy integration of various SSO options.

Supported Authentication Providers

• OAuth2 providers using remix-auth
• OpenID Connect providers via web-oidc
• SAML support through @boxyhq/remix-auth-sso

GitHub OAuth Integration

The stack comes pre-configured with GitHub OAuth2 authentication. Here's how to set it up:

Local Development Setup

1. Create a GitHub OAuth application:

   • Go to GitHub Developer Settings > OAuth Apps
   • Click "Register a new application"
   • Set Homepage URL to http://localhost:3000
   • Set Authorization callback URL to http://localhost:3000/auth/github/callback
   • Choose a meaningful application name
   • Save the application

2. Configure Environment Variables:

   # .env file
   GITHUB_CLIENT_ID="your_client_id"
   GITHUB_CLIENT_SECRET="your_client_secret"

Development Testing

The system includes a mock GitHub server for development using MSW (Mock Service Worker):

• Set GITHUB_CLIENT_ID to MOCK_... to use the mock server
• This intercepts GitHub OAuth requests during development
• Enables testing without real GitHub credentials

Production Configuration

For production environments:

1. Create separate OAuth applications for each environment:

   • Development
   • Staging
   • Production

2. Use appropriate callback URLs for each environment:

   Development: http://localhost:3000/auth/github/callback
   Staging: https://staging.yourapp.com/auth/github/callback
   Production: https://yourapp.com/auth/github/callback
   

3. Configure environment-specific secrets in your deployment platform

Two-Factor Authentication (2FA)

The stack implements a robust Two-Factor Authentication system using Time-based One-Time Passwords (TOTP).

TOTP Implementation

The TOTP system provides:

• Secure secret generation and storage
• Time-based code validation
• Support for multiple verification flows

Security Features

1. Verification Types:

   • Standard 2FA authentication
   • Email verification codes
   • Password reset verification
   • Email change verification

2. Security Measures:

   • 2-hour time limit on 2FA verifications
   • Required for sensitive operations
   • Secure secret storage in database
   • Protection against brute force attacks

Required 2FA Actions

Users with 2FA enabled must verify within a 2-hour window for:

• Changing email address
• Disabling 2FA
• Other destructive actions
• Password changes
• Account deletion

Implementation Details

The TOTP system stores verification data in a dedicated database model with:

• Encrypted secrets
• Expiration timestamps
• Usage tracking
• Automatic cleanup of expired codes

Session Management

The authentication system uses a sophisticated session management approach:

Session Features

1. Secure Storage:

   • HTTP-only cookies
   • Encrypted session data
   • Database-backed sessions

2. Session Controls:

   • Individual session revocation
   • Multi-device session tracking
   • Automatic expiration
   • Last-used tracking

3. Security Measures:

   • CSRF protection
   • Rate limiting
   • Secure cookie settings
   • Session fixation prevention

Session Database Model

Sessions are stored in a dedicated database table with:

• Unique session identifiers
• User associations
• Creation timestamps
• Last accessed timestamps
• Device information
• Automatic cleanup of expired sessions

Security Best Practices

The authentication system implements several security best practices:

1. Password Security:

   • Bcrypt hashing
   • Password strength requirements
   • Brute force protection
   • Secure password reset flow

2. Email Security:

   • Verified email addresses
   • Secure email change process
   • Rate limited email actions

3. Session Security:

   • Short-lived sessions
   • Secure session storage
   • Session revocation
   • Cross-site request forgery protection

4. Rate Limiting:

   • Login attempts
   • Password reset requests
   • Email verification attempts
   • 2FA attempts

For more detailed information about security measures, visit the security documentation. For deployment configuration details, check the deployment guide.