Auth0 Custom Database — Migrate Existing Users to Auth0

# custom_db_setup.py
# Custom database connection setup

def custom_db_config():
    print("Custom Database Connection Setup:")
    print()
    print("1. Auth0 Dashboard > Authentication > Database")
    print("2. Create a new database connection")
    print("3. Name: Legacy-Users-DB")
    print("4. Disable 'Auth0 will manage user identities'")
    print("5. Enable 'Use my own database'")
    print()
    print("Connection settings:")
    print("  - Database name in Auth0: Legacy-Users-DB")
    print("  - Your database type: MySQL/PostgreSQL/MongoDB")
    print("  - Connection method: Custom scripts")
    print("  - Import mode: Disabled (we use custom scripts)")

custom_db_config()

// Custom Database Script: Login
// This script runs when a user tries to log in

function login(email, password, callback) {
  const mysql = require('mysql2');
  
  const connection = mysql.createConnection({
    host: configuration.DB_HOST,
    user: configuration.DB_USER,
    password: configuration.DB_PASSWORD,
    database: configuration.DB_NAME
  });
  
  connection.query(
    'SELECT id, email, password_hash, name FROM users WHERE email = ?',
    [email],
    function(err, results) {
      if (err) {
        callback(new Error('Database error'));
        return;
      }
      
      if (results.length === 0) {
        callback(new WrongUsernameOrPasswordError(email));
        return;
      }
      
      const user = results[0];
      
      // Verify password (using bcrypt)
      const bcrypt = require('bcrypt');
      bcrypt.compare(password, user.password_hash, function(err, isValid) {
        if (err || !isValid) {
          callback(new WrongUsernameOrPasswordError(email));
          return;
        }
        
        callback(null, {
          user_id: user.id.toString(),
          email: user.email,
          name: user.name,
          app_metadata: {
            migrated_from: 'legacy'
          }
        });
      });
      
      connection.end();
    }
  );
}

# login_script.py
# Understanding the login script

def login_script_requirements():
    print("Login Script Requirements:")
    print()
    print("Input:")
    print("  - email (string): User's email address")
    print("  - password (string): User's password (plaintext)")
    print()
    print("On success, callback with user profile:")
    print("  { user_id, email, name, app_metadata, ... }")
    print()
    print("On failure:")
    print("  callback(new WrongUsernameOrPasswordError(email))")
    print("  or callback(new Error('reason'))")
    print()
    print("Available variables:")
    print("  - configuration: Custom settings from Auth0")
    print("  - global: shared global object")
    print("  - require(): Node.js modules")

login_script_requirements()

// Custom Database Script: Login (with progressive migration)

function login(email, password, callback) {
  // First, try Auth0's managed database
  const db = connection;
  
  db.query('SELECT * FROM users WHERE email = ?', [email], (err, results) => {
    if (err) {
      callback(new Error('Database error'));
      return;
    }
    
    if (results.length === 0) {
      // User not in legacy database
      callback(new WrongUsernameOrPasswordError(email));
      return;
    }
    
    const user = results[0];
    // Verify password...
    
    // After successful verification:
    // Import the user to Auth0's managed database
    callback(null, {
      user_id: user.id.toString(),
      email: user.email,
      name: user.name,
      // Mark as migrated
      app_metadata: { migrated: true }
    });
    
    // On next login, Auth0 finds the user in its own database
    // and skips the custom database script
  });
}

# progressive_migration.py
# Progressive migration strategy

def migration_phases():
    print("Progressive Migration Phases:")
    print()
    print("Phase 1: Custom Database Only")
    print("  - Auth0 delegates all authentication to legacy DB")
    print("  - No users in Auth0's managed database")
    print("  - Login script reads from legacy DB")
    print()
    print("Phase 2: Progressive Migration Active")
    print("  - Login script returns user profile")
    print("  - Auth0 automatically copies user to managed DB")
    print("  - After first successful login, user is migrated")
    print()
    print("Phase 3: Import Complete")
    print("  - Most users have been migrated")
    print("  - Disable custom database (make it read-only)")
    print("  - Only remaining users use the custom DB")
    print()
    print("Phase 4: Legacy Decommission")
    print("  - All users migrated to Auth0")
    print("  - Remaining non-migrated users receive password reset")
    print("  - Legacy database can be archived")

migration_phases()

# password_handling.py
# Legacy password hash handling

def password_strategies():
    strategies = {
        "bcrypt": "Supported natively by Auth0. Use bcrypt.compare in login script.",
        "pbkdf2": "Use Node.js crypto.pbkdf2Sync in login script.",
        "MD5/SHA1": "Wrapped hashes: convert legacy hash + salt to bcrypt format.",
        "Argon2": "Use argon2 npm package in login script.",
        "Custom algorithm": "Implement your verification function in the login script.",
        "Plaintext": "Strongly discouraged. Upgrade to bcrypt during migration.",
    }
    
    print("Password Hash Strategy:")
    for hash_type, strategy in strategies.items():
        print(f"  {hash_type:20s} | {strategy}")

password_strategies()

def migration_project_plan():
    print("Migration Project Plan:")
    print()
    print("Phase 1: Setup (Week 1)")
    print("  - Create custom database connection")
    print("  - Write login script with bcrypt verification")
    print("  - Write get_user script")
    print("  - Test with development database")
    print()
    print("Phase 2: Progressive Migration (Week 2-3)")
    print("  - Deploy to production")
    print("  - Monitor migration progress")
    print("  - Handle edge cases (duplicate emails, missing profiles)")
    print()
    print("Phase 3: Decommission (Week 4)")
    print("  - Verify all active users migrated")
    print("  - Send password reset emails to inactive users")
    print("  - Archive legacy database")

migration_project_plan()