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.182 core updates– More
    23 July 2021
  • ProcessWire 3.0.181 has fixes and improvements as usual, but the biggest addition is a nice pull request for multi-language module translations, plus major updates to our Helloworld and ProcessHello demonstration modules. This post covers it all— More
    2 July 2021
  • ProcessWire 3.0.180 core updates– More
    18 June 2021

Latest news

  • ProcessWire Weekly #377
    In the 377th issue of ProcessWire Weekly we'll cover the latest core updates, highlight some recent online resources, and more. Read on!
    Weekly.pw / 31 July 2021
  • ProcessWire 3.0.181 core updates + “Hello World”
    ProcessWire 3.0.181 has fixes and improvements as usual, but the biggest addition is a nice pull request from LostKobrakai, plus major updates to our Helloworld and ProcessHello demonstration modules. This post covers it all.
    Blog / 2 July 2021
  • Subscribe to weekly ProcessWire news

“We were really happy to build our new portfolio website on ProcessWire! We wanted something that gave us plenty of control on the back-end, without any bloat on the front end - just a nice, easy to access API for all our content that left us free to design and build however we liked.” —Castus, web design agency in Sheffield, UK