Setting Up Password Resets

The login module includes a built-in forgot-password flow. When a user forgets their password, they can request a reset link, which is sent to their email address via the trongate_email module.

This page walks through the complete setup.

Prerequisites

• The login module in your modules/ directory (included with Trongate v2)
• The trongate_email module in your modules/ directory (included with Trongate v2)
• A configured trongate_email.php config file
• SMTP credentials for sending emails

Step 1: Configure the Email Module

Create config/trongate_email.php with your SMTP server details:

Common SMTP configurations:

Step 2: Configure the Login Module

Open config/login.php. The forgot-password feature uses these settings:

The reset_token_lifespan setting controls how long a reset link remains valid. The default is 3600 seconds (1 hour).

Step 3: Test the Forgot Password Flow

Navigate to the forgot-password form at:

1. Enter the email address associated with the user account
2. Submit the form
3. Check the inbox for the reset email
4. Click the reset link and set a new password

If you have configured custom routes (see Working with Login Routes), adjust the URL accordingly.

How It Works

When a user requests a password reset:

1. The login module looks up the user by email address in the configured target table
2. A cryptographically random token is generated and stored in the trongate_tokens table
3. An email is sent via trongate_email containing a reset link with the token
4. The user clicks the link and sets a new password
5. All existing authentication tokens for that user are destroyed, forcing a re-login everywhere

This last step is critical for security — if an attacker had access to an active session, changing the password invalidates all sessions immediately.

Customising the Reset Email

The forgot-password email is built by the Login_model and sent via trongate_email. The email contains:

• A greeting
• The reset link (with a time-sensitive token)
• An expiry notice
• A warning to ignore if not requested

The email is sent as an HTML-formatted message. The trongate_email module automatically generates a plain-text version from the HTML.

Troubleshooting

Email Not Received

• Check that config/trongate_email.php exists and has valid SMTP credentials
• Verify the SMTP host and port are correct for your provider
• Check your server allows outbound connections on the SMTP port
• Check spam folders
• Test the SMTP configuration separately using the trongate_email module

Reset Link Expires Immediately

• Check that server time is accurate (clock drift can cause tokens to be considered expired)
• Increase reset_token_lifespan in config/login.php

User Not Found

• Verify the email identifier column matches your database column name
• Check that the user level ID in the config matches the user's level