Migrating to the Universal Login Module

Trongate now ships with a Universal Login Module that replaces the authentication built into the trongate_administrators module. The new module supports multiple user levels, works with any user table (administrators, members, subscribers, etc.), and offers three configurable view styles.

This guide walks you through upgrading an existing Trongate project.

What Changed

The trongate_administrators module previously handled its own login, logout, and authentication logic. In the new architecture, all authentication is handled by the login module. The old methods — login(), submit_login(), log_user_in(), login_check(), not_allowed(), police_secret_login_url(), and make_sure_login_attempt_allowed() — have been removed from the trongate_administrators controller.

The login module handles credential validation, token generation, failed attempt tracking, and session management. The trongate_administrators module now focuses purely on user administration (create, edit, delete, manage).

Prerequisites

• Trongate v2.0 or higher
• The login module present in your modules/ directory
• The config/login.php configuration file
• The config/login_routes.php routing file (if using custom routing)

Step-by-Step Migration

Step 1: Copy the New Modules

Copy the following directories from the latest Trongate release into your project:

• modules/login/ — The new login module (including forgot_password/ child module)
• modules/trongate_administrators/ — The updated administrators module (without its own auth)

Step 2: Copy the Configuration Files

Copy these files from the latest release:

• config/login.php — Login module configuration (user level mappings, view style, redirect URLs)
• config/login_routes.php — Optional routing for custom login URLs

Step 3: Configure the Login Module

Open config/login.php. This file defines how the login module works for each user level. A typical configuration for administrators looks like this:

About the Identifiers Array

The identifiers array replaces the single identifier field from earlier versions. Each entry defines a column name and label for an acceptable login identifier. Users can log in with any of the configured identifiers — for example, an administrator can use either their username or their email address, along with their password.

Map your database column names directly. Common examples:

If your table only supports one identifier (e.g. email-only for a members table), simply declare a single entry:

The label you set determines what the login form shows. When multiple identifiers are configured, they are combined automatically (e.g. "Username or Email").

Step 4: Update the Updated Administrators Module

If you have made custom changes to your trongate_administrators module, you will need to merge the changes rather than overwriting. The key modifications are:

1. Remove the $secret_login_segment property — This concept has been removed. The login module uses public URLs.
2. Update logout() — It should now redirect to login/logout instead of a local login URL.
3. Update make_sure_allowed() — It should redirect to login/login when unauthenticated, instead of trying to auto-login or redirecting to a secret URL.
4. Remove login-related methods — Remove login(), submit_login(), log_user_in(), login_check(), not_allowed(), police_secret_login_url(), and make_sure_login_attempt_allowed().
5. Remove auth-related model methods — Remove validate_credentials(), verify_password(), get_timing_safe_hash(), log_user_in(), after_login_tasks(), is_login_attempt_allowed(), remove_expired_restrictions(), increment_failed_login_attempts(), and get_any_active_user().
6. Remove old views — Delete modules/trongate_administrators/views/login.php and not_allowed.php.

Step 5: Update Custom Routing (If Applicable)

If your project used custom routing to alias the admin login URL (e.g., tg-admin), you can remove those routes. The new login module uses the URL login/login, which is intentionally public and discoverable — this is more secure than obscurity.

If you were using routing like this:

You can now remove it, or repurpose it to redirect to the login module:

View Styles

The login module ships with three view styles, configurable via the view_file setting in each user level's configuration:

What You Gain

• Multi-table support — Authenticate against any user table, not just trongate_administrators
• Multi-identifier login — Users can log in with their username, email address, or any combination defined in your config
• Configurable view styles — Choose from three different login page layouts
• Forgot password flow — Built-in password reset with email delivery via the trongate_email module and token-based reset links
• Brute-force protection — Configurable rate limiting and failed-attempt tracking
• Timing-safe hash comparison — Protection against timing-based enumeration attacks
• No secret URLs — The system is secure by design, not by obscurity
• Cleaner module — The administrators module now handles only administration, not authentication

Rollback

If you need to revert, the old trongate_administrators module is still available in previous releases. To roll back:

1. Restore your previous trongate_administrators controller and model
2. Remove or rename the modules/login/ directory
3. Restore any custom routing that pointed to trongate_administrators/login