nojimage/cakephp-remember-me

RememberMe authentication adapter plugin for CakePHP

v5.0.0 2024-02-09 08:31 UTC

Requires

• php: >=8.1
• ext-json: *
• cakephp/authentication: ^3.0
• cakephp/core: ^5.0
• cakephp/orm: ^5.0

Requires (Dev)

• cakephp/cakephp: ^5.0
• cakephp/cakephp-codesniffer: ^5.1
• cakephp/migrations: ^4.0
• phpunit/phpunit: ^10.1

MIT

• Authentication
• cakephp
• auth
• cookie
• remember-me

README

This plugin provides an authenticate handler that permanent login by cookie. This plugin use method of issuing a token, instead of set to cookie encrypted username/password.

This library inspired by Barry Jaspan's article "Improved Persistent Login Cookie Best Practice", and Gabriel Birke's libray "https://github.com/gbirke/rememberme".

Installation

You can install this plugin into your CakePHP application using composer.

The recommended way to install composer packages is:

php composer.phar require nojimage/cakephp-remember-me:^5.0

Load the plugin by adding the following statement in your project's src/Application.php:

$this->addPlugin('RememberMe');

or running the console command

bin/cake plugin load RememberMe

Run migration:

bin/cake migrations migrate -p RememberMe

Usage with Authentication plugin

If you're using cakephp/authentication, use RememberMeTokenIdentifier and CookeAuthenticator.

Example load RememberMe's Identifier and Authenticator into the getAuthenticationService hook within Application:

// in your src/Application.php
class Application extends ...
{
    public function getAuthenticationService(...): void
    {
        $service = new AuthenticationService();
        $fields = [
            'username' => 'email',
            'password' => 'password'
        ];
        // ... setup other identifier and authenticator

        // setup RememberMe
        $service->loadIdentifier('RememberMe.RememberMeToken', compact('fields'));
        $service->loadAuthenticator('RememberMe.Cookie', [
            'fields' => $fields,
            'loginUrl' => '/users/login',
        ]);
    }
}

more document for getAuthenticationService, see: Quick Start - CakePHP Authentication 3.x

RememberMe.RememberMeTokenIdentifier options

fields

The fields for the lookup.

default: ['username' => 'username']

    $service->loadIdentifier('RememberMe.RememberMeToken', [
        'fields' => [
            'username' => 'email',
        ],
    ]);

resolver

The identity resolver. If change your Resolver, must extend Authentication\Identifier\Resolver\OrmResolver.

default: 'Authentication.Orm'

    $service->loadIdentifier('RememberMe.RememberMeToken', [
        'resolver' => [
            'className' => 'Authentication.Orm',
            'userModel' => 'Administrators',
        ],
    ]);

tokenStorageModel

A model used for find login cookie tokens.

default: 'RememberMe.RememberMeTokens'

    $service->loadIdentifier('RememberMe.RememberMeToken', [
        'tokenStorageModel' => 'YourTokensModel',
    ]);

userTokenFieldName

A property name when adding token data to identity.

default: 'remember_me_token'

    $service->loadIdentifier('RememberMe.RememberMeToken', [
        'userTokenFieldName' => 'cookie_token',
    ]);

RememberMe.CookeAuthenticator options

loginUrl

The login URL, string or array of URLs. Default is null and all pages will be checked.

default: null

    $service->loadAuthenticator('RememberMe.Cookie', [
        'loginUrl' => '/users/login',
    ]);

urlChecker

The URL checker class or object.

default: 'DefaultUrlChecker'

    $service->loadAuthenticator('RememberMe.Cookie', [
        'loginUrl' => '/users/login',
    ]);

rememberMeField

When this key is input by form authentication, it issues a login cookie.

default: 'remember_me'

    $service->loadAuthenticator('RememberMe.Cookie', [
        'rememberMeField' => 'remember_me',
    ]);

fields

Array that maps username to the specified POST data fields.

default: ['username' => 'username']

    $service->loadAuthenticator('RememberMe.Cookie', [
        'fields' => [
            'username' => 'email',
        ],
    ]);

cookie

Write option for login cookie.

• name: Cookie name (default: 'rememberMe')
• expire: Cookie expiration (default: '+30 days')
• path: Path (default: '/')
• domain: Domain, (default: '')
• secure: Secure flag (default: true)
• httpOnly: Http only flag (default: true)

    $service->loadAuthenticator('RememberMe.Cookie', [
        'cookie' => [
            'name' => 'rememberMe',
            'expires' => '+30 days',
            'secure' => true,
            'httpOnly' => true,
        ],
    ]);

tokenStorageModel

A model used for storing login cookie tokens.

default: 'RememberMe.RememberMeTokens'

    $service->loadAuthenticator('RememberMe.Cookie', [
        'tokenStorageModel' => 'YourTokensModel',
    ]);

always

When this option is set to true, a login cookie is always issued after authentication identified.

default: false

    $service->loadAuthenticator('RememberMe.Cookie', [
        'always' => true,
    ]);

dropExpiredToken

When this option is set to true, drop expired tokens after authentication identified.

default: true

    $service->loadAuthenticator('RememberMe.Cookie', [
        'dropExpiredToken' => false,
    ]);