LoginPersist by craig-a-rodway

Persist user logins across browser sessions.

LoginPersist

By Craig A Rodway.

License: GPL v3 ProcessWire 3

LoginPersist is a module for the ProcessWire CMS/CMF that provides "Remember Me" functionality for users so that they can remain logged in across browser sessions.

The module follows recommendations documented here:

Features


  • Automatic or manual mode.
  • Options can be changed in the module configuration page.
  • Enable fingerprinting (IP address and User Agent) as an additional security check.
  • Limit the persistent login functionality by role (enable or disable based on specific roles).
  • Set the name and age of the cookie.
  • Sets an identifier in the session when a user is logged in via a persistent login cookie. This should be used to control access to sensitive information and actions within your site's custom code.
  • Clears login tokens when a potential theft has been identified.

Automatic mode

This requires no code changes, and uses ProcessWire login hooks to run the persistent code. When logging in, users do not have a choice whether to remain logged in or not.

Manual mode

You you have full control over when and where you call the module's persistence code. This allows you to provide users with the choice of staying logged in or not.

Requirements


You will need the following to make use of this module:

  • PHP 5.6.30 or newer
  • ProcessWire 3.0.34 or newer

Installing


From the Modules Directory

  1. Visit the Site > Modules page in your website's admin panel.
  2. Click the 'New' tab.
  3. Enter 'LoginPersist' in the 'Module Class Name' field and click 'Get Module Info'.
  4. Click the 'Download Now' button.
  5. Cick the 'Install Now' button.

Manually

  1. Place the module files in the /site/modules/LoginPersist directory.
  2. Visit the Site > Modules page in your website's admin panel.
  3. Press the 'Refresh' button.
  4. In the 'New' tab, find LoginPersist in the list and click the 'Install' button.

How it works


The 'stay logged in' functionality is provided by setting a new cookie for the user after they have successfully logged in.

The next time the user visits the site after their standard ProcessWire session has naturally expired, they will be treated as any other 'guest' user. This module checks for the presence of a persistent cookie belonging to a visitor, and will log them in.

When a user logs out (triggered with the hook Session::logoutSuccess) their persistent cookie will be removed, along with the corresponding entries in the database.

Configuring


General Settings

Automatic mode

Enable or disable the automatic mode. When a user logs in successfully, they will be given a persistent login cookie, after passing the roles checks.

Use fingerprint

Enables or diables user fingerprint checking - a user's IP address and user agent. This determines if the user's fingerprint should be checked on return visits and when being logged in via a persistent cookie against their fingerprint stored in the database at the time the cookie was created.

See ProcessWire sessionFingerprint configuration value help for more details on what level of fingerprinting is available and best for your situation.

Session identifier

Set the name of the session variable that is set to true when a user is logged in via a persistent cookie.

This is useful if you want to implement additional authentication checks in your site's code when a user wants to access an area or action that requires more security. Examples of these could be changing passwords or authentication details, or deleting data or accounts.

The name of the cookie given to users for persistent logins. Cookie names should be kept short.

The length of time that cookies will be valid for. Change this to suit your needs and the length of time between typical user visits.

Roles

You can control which user roles can use the persistent login functionality using the Roles configuration - using Allow and Deny lists. Role checking operates in automatic and manual modes.

Leaving both lists empty effectively disables all role checking, allowing any user to stay logged in. The Deny list takes precedence over the allow list.

Role checking runs at the point of issuing cookies as well as checking for them to log a user in.

Allow

When there are one or more roles selected, only users in the selected roles will be permitted to stay logged in.

Deny

When there are one or more roles selected, users in these roles will not be allowed to stay logged in. Users in any other roles will be allowed.

Using


Automatic mode

Automatic mode works by hooking the Session::loginSuccess() method which is triggered when a user logs in successfully. This means that it works for back-end as well as front-end logins.

At this point, and if the user passes the necessary roles checks, a cookie is generated and a corresponding database entry is made.

Manual mode

In manual mode, you must call a module function yourself to create the persistent login cookie.

For example, this can be in response to a 'Remember Me' checkbox on a login form, indicating their preference to remain logged in.

You can use any of the below methods once you have authenticated the user attempting to log in:

1 - calling the hooked method persist() on the ProcessWire Session class.

This means you don't have to load and reference LoginPersist module.

wire('session')->persist();

2 - calling the persist() method on LoginPersist.

$loginPersist = wire('modules')->get('LoginPersist');
$loginPersist->persist();

Hooking checkRoles

This method is responsible for checking if the user passes the denied and allowed roles checks. You can add an 'after' hook to LoginPersist::checkRoles() to modify the return value ($event->return) if you need to. The value should be true or false.

You might want to do this to check some extra conditions beyond the allow or deny roles, or have some exceptions to the rules.

$wire->addHookAfter('LoginPersist::checkRoles', function(HookEvent $event) {
	$user = $event->arguments(0);
	// Allow user1, regardless of role
	if ($user->name == 'user1') {
		$event->return = true;
	}
	// Never remember user2
	if ($user->name == 'user2') {
		$event->return = false;
	}
});

Install and use modules at your own risk. Always have a site and database backup before installing new modules.

Twitter updates

  • ProcessWire 3.0.185 (dev) core updates, plus new Session Allow module— More
    17 September 2021
  • Three new ProcessWire Textformatter modules: Find/Replace, Markdown in Markup, and Emoji— More
    3 September 2021
  • This week we have a new master version released after a year in the making. With nearly 40 pull requests, hundreds of new additions and more than 100 issue reports resolved, this new version has a ton of great new stuff— More
    27 August 2021

Latest news

  • ProcessWire Weekly #385
    In the 385th issue of ProcessWire Weekly we'll cover the latest weekly update from Ryan, check out a new fieldtype module called Page Reference Context Data, and more. Read on!
    Weekly.pw / 25 September 2021
  • ProcessWire 3.0.184 new master/main version
    This week we have a new master/main version released after a full year in the making. As you might imagine, this new version has a ton of great new stuff and we’ll try to cover much of it here.
    Blog / 27 August 2021
  • Subscribe to weekly ProcessWire news

“…building with ProcessWire was a breeze, I really love all the flexibility the system provides. I can’t imagine using any other CMS in the future.” —Thomas Aull