HomeGithubDiscordBlog

Forgot Password

OpenAlgo Password Reset System

Overview

OpenAlgo provides a comprehensive dual-mode password reset system that allows users to recover their accounts through either:

  1. TOTP (Time-based One-Time Password) authentication

  2. Email verification (requires SMTP configuration)

This system is designed with security best practices and provides fallback options for different scenarios.

Table of Contents

  • System Architecture

  • Authentication Methods

  • Setup Requirements

  • User Flow

  • Configuration Guide

  • Security Features

  • Troubleshooting

  • API Endpoints

  • Rate Limiting

System Architecture

The password reset system follows a secure token-based approach with multiple verification methods:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   User Request  │    │  Method Selection │    │  Verification   │
│                 │───▶│                  │───▶│                 │
│ Enter Email     │    │ TOTP or Email    │    │ Code/Link Check │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                          │
                       ┌─────────────────┐               │
                       │  Password Reset │◀──────────────┘
                       │                 │
                       │ New Password    │
                       └─────────────────┘

Authentication Methods

1. TOTP Authentication (Recommended)

Advantages:

  • Works offline

  • No external dependencies

  • Immediate verification

  • Always available

Requirements:

  • User must have TOTP configured

  • Authenticator app (Google Authenticator, Authy, etc.)

Flow:

  1. User enters email address

  2. User selects "TOTP Authentication"

  3. User enters TOTP code from authenticator app

  4. System validates code and allows password reset

2. Email Verification

Advantages:

  • User-friendly

  • No additional app required

  • Secure email delivery

Requirements:

  • SMTP configuration must be completed

  • User has access to their email

Flow:

  1. User enters email address

  2. User selects "Email Verification"

  3. System sends reset link to user's email

  4. User clicks link and resets password

Setup Requirements

TOTP Setup (Always Available)

TOTP is automatically configured during account creation. Each user gets:

  • Unique TOTP secret key

  • QR code for easy setup

  • Backup secret for manual entry

SMTP Configuration (Required for Email Reset)

Personal Gmail Configuration:

SMTP Server: smtp.gmail.com
Port: 587 (STARTTLS) or 465 (SSL/TLS)
Username: [email protected]
Password: [App Password - NOT regular password]
HELO Hostname: smtp.gmail.com
Use TLS: Yes

Gmail Workspace Configuration:

SMTP Server: smtp-relay.gmail.com
Port: 465 (SSL/TLS)
Username: [email protected]
Password: [App Password]
HELO Hostname: smtp.gmail.com
Use TLS: Yes

App Password Setup for Gmail:

  1. Go to Google Account Settings

  2. Navigate to Security → 2-Step Verification

  3. Select "App passwords"

  4. Generate a new app password for "Mail"

  5. Use this password in SMTP configuration

User Flow

Password Reset Process

  1. Initial Request

    • User visits /auth/reset-password

    • Enters email address

    • System validates email format (client-side and server-side)

  2. Method Selection

    • System presents two verification options:

      • TOTP Authentication (always available)

      • Email Verification (if SMTP configured)

    • User selects preferred method

  3. TOTP Verification Path

    • User enters TOTP code from authenticator app

    • System validates code against user's TOTP secret

    • If valid, generates secure reset token

    • User proceeds to password reset form

  4. Email Verification Path

    • System generates secure reset token

    • Sends password reset email with secure link

    • User clicks link in email

    • System validates token and shows password reset form

  5. Password Reset

    • User enters new password

    • System validates password meets requirements:

      • Minimum 8 characters

      • At least 1 uppercase letter (A-Z)

      • At least 1 lowercase letter (a-z)

      • At least 1 number (0-9)

      • At least 1 special character (@#$%^&*)

    • Password is hashed and stored securely

    • All reset tokens are invalidated

Configuration Guide

SMTP Configuration

Access SMTP settings at /auth/change → "SMTP Configuration" tab:

  1. Server Settings

    • Enter SMTP server hostname

    • Set appropriate port (587 for STARTTLS, 465 for SSL/TLS)

    • Configure HELO hostname

  2. Authentication

    • Enter username (usually email address)

    • Enter App Password (not regular password for Gmail)

    • Set from email address

  3. Security

    • Enable TLS/SSL encryption

    • Test configuration before saving

  4. Testing

    • Use "Send Test" to verify configuration

    • Use "Debug" for detailed connection diagnostics

TOTP Configuration

Access TOTP settings at /auth/change → "TOTP Authentication" tab:

  1. QR Code Setup

    • Scan QR code with authenticator app

    • Or manually enter the secret key

  2. Supported Apps

    • Google Authenticator

    • Authy

    • Microsoft Authenticator

    • 1Password

    • Bitwarden

  3. Backup

    • Save secret key in secure location

    • Test TOTP generation before relying on it

Security Features

Token Security

  • Cryptographically secure tokens: 32-byte URL-safe tokens

  • Session-based validation: Tokens stored in server-side sessions

  • Single-use tokens: Tokens invalidated after successful use

  • Time-limited validity: Email tokens expire with session

  • Secure transmission: HTTPS-only token delivery

Anti-Enumeration Protection

  • Consistent responses: Same response regardless of email existence

  • Information leakage prevention: No indication if email is registered

  • Rate limiting: Prevents brute force attacks

Additional Security Measures

  • CSRF protection: All forms protected with CSRF tokens

  • Input validation: Email format and password strength validation

  • Secure password hashing: Bcrypt with proper salt rounds

  • Session security: Secure session cookie configuration

Troubleshooting

Common SMTP Issues

Gmail Authentication Failed

Error: SMTP Authentication failed
Solution: Use App Password instead of regular password
Steps: Google Account → Security → 2-Step Verification → App passwords

Gmail Workspace Relay Denied

Error: Mail relay denied
Solution 1: Register server IP in Google Admin Console
Solution 2: Switch to personal Gmail settings (smtp.gmail.com:587)

Connection Timeout

Error: Connection timeout
Check: Firewall blocking SMTP ports (587, 465)
Check: Network connectivity to SMTP server

SSL/TLS Errors

Error: SSL handshake failed
Solution: Verify port configuration (587=STARTTLS, 465=SSL/TLS)
Check: Certificate validation settings

Common TOTP Issues

Invalid TOTP Code

Issue: Code not accepted
Check: Time synchronization on device
Check: Code not expired (30-second window)
Solution: Manually sync time in authenticator app

Lost Authenticator Device

Issue: Cannot generate TOTP codes
Solution: Use backup secret key to reconfigure
Fallback: Contact administrator for manual reset

Email Delivery Issues

Email Not Received

Check: Spam/junk folder
Check: Email address typos
Check: SMTP server logs
Verify: Test email functionality works

Reset Link Expired

Issue: "Invalid or expired reset link"
Cause: Session expired or link already used
Solution: Request new password reset

⚠️ Nuclear Option: Complete Database Reset

When All Else Fails

If you cannot access your OpenAlgo account through any method (TOTP broken, email not working, lost credentials), 1)stop openalgo application 2)Locate the file openalgo.db from the db folder 3)delete the openalgo.db database file form the /db folder 4)restart the openalgo application 5)Start signup with openalgo fresh 6)Ensure Gmail SMTP Settings or TOTP Authenticator is Configured

What You Will Lose

⚠️ WARNING: This action is irreversible and will permanently delete:

  • User accounts and passwords

  • All trading logs and history

  • API access logs and analytics

  • Strategy configurations and backtests

  • SMTP/email settings

  • Rate limiting history

  • System settings and preferences

  • Custom configurations

Prevention for Future

To avoid needing database reset:

  1. Save TOTP Secret Key: Store authenticator backup codes securely

  2. Configure SMTP Early: Set up email recovery before you need it

  3. Document Credentials: Keep encrypted record of important settings

  4. Regular Backups: Schedule automatic database backups

  5. Test Recovery: Periodically test password reset functionality

Alternative Recovery Methods

Before resorting to database reset, try these:

  1. TOTP Secret Recovery: If you saved the original secret key, re-add to authenticator

  2. Database Editing: Advanced users can directly edit SQLite database to reset passwords

  3. Python Script Recovery: Create custom script to reset user password in database

  4. Backup Restoration: If you have recent database backup, restore it instead

Rate Limiting

The password reset system implements rate limiting to prevent abuse:

Configuration

# Login rate limits (applied to reset password as well)
LOGIN_RATE_LIMIT_MIN=5 per minute
LOGIN_RATE_LIMIT_HOUR=25 per hour

# Password reset specific limit
RESET_RATE_LIMIT=15 per hour

Limits Applied

  • Password reset requests: 15 per hour per IP

  • SMTP test requests: Inherits from login limits

  • Failed authentication attempts: Tracked separately

Rate Limit Headers

When rate limited, responses include:

  • X-RateLimit-Limit: Maximum requests allowed

  • X-RateLimit-Remaining: Requests remaining in window

  • X-RateLimit-Reset: Time when limit resets

Best Practices

For Users

  1. TOTP Setup: Always configure TOTP as primary recovery method

  2. Backup Codes: Save TOTP secret key securely

  3. Email Security: Use secure email provider with 2FA

  4. Strong Passwords: Follow password requirements strictly

PreviousTOTP ConfigurationNextUpgrade

Last updated