Using Session Authenticator

Session authenticator provides traditional ID/Password authentication.

Learning any new authentication system can be difficult, especially as they get more flexible and sophisticated. This guide is intended to provide short examples for common actions you'll take when working with Shield. It is not intended to be the exhaustive documentation for each section. That's better handled through the area-specific doc files.

Note

The examples assume that you have run the setup script and that you have copies of the Auth and AuthGroups config files in your application's app/Config folder.

Configuration

Configure Redirect URLs

If you need everyone to redirect to a single URL after login/logout/register actions, you can modify the Config\Auth::$redirects array in app/Config/Auth.php to specify the url to redirect to.

By default, a successful login or register attempt will all redirect to /, while a logout action will redirect to a named route login or a URI path /login. You can change the default URLs used within the app/Config/Auth.php config file:

public array $redirects = [
    'register' => '/',
    'login'    => '/',
    'logout'   => 'login',
];

Note

This redirect happens after the specified action is complete. In the case of register or login, it might not happen immediately. For example, if you have any Auth Actions specified, they will be redirected when those actions are completed successfully. If no Auth Actions are specified, they will be redirected immediately after registration or login.

Configure Remember-me Functionality

Remember-me functionality is enabled by default. While this is handled in a secure manner, some sites may want it disabled. You might also want to change how long it remembers a user and doesn't require additional login.

public array $sessionConfig = [
    'field'              => 'user',
    'allowRemembering'   => true,
    'rememberCookieName' => 'remember',
    'rememberLength'     => 30 * DAY,
];

Enable Account Activation via Email

Note

You need to configure app/Config/Email.php to allow Shield to send emails. See Installation.

By default, once a user registers they have an active account that can be used. You can enable Shield's built-in, email-based activation flow within the Auth config file.

public array $actions = [
    'register' => \CodeIgniter\Shield\Authentication\Actions\EmailActivator::class,
    'login'    => null,
];

Enable Two-Factor Authentication

Note

You need to configure app/Config/Email.php to allow Shield to send emails. See Installation.

Turned off by default, Shield's Email-based 2FA can be enabled by specifying the class to use in the Auth config file.

public array $actions = [
    'register' => null,
    'login'    => \CodeIgniter\Shield\Authentication\Actions\Email2FA::class,
];

Customizing Routes

If you need to customize how any of the auth features are handled, you can still use the service('auth')->routes() helper, but you will need to pass the except option with a list of routes to customize:

service('auth')->routes($routes, ['except' => ['login', 'register']]);

Then add the routes to your customized controllers:

$routes->get('login', '\App\Controllers\Auth\LoginController::loginView');
$routes->get('register', '\App\Controllers\Auth\RegisterController::registerView');

Check your routes with the spark routes command.

Protecting Pages

By default, Shield does not protect pages. To make certain pages accessible only to logged-in users, set the session controller filter.

For example, if you want to limit all routes (e.g. localhost:8080/admin, localhost:8080/panel and ...), you need to add the following code in the app/Config/Filters.php file.

public $globals = [
    'before' => [
        // ...
        'session' => ['except' => ['login*', 'register', 'auth/a/*', 'logout']],
    ],
    // ...
];

Note

The filter $aliases that Shield provides are automatically added for you by the Registrar class located at src/Config/Registrar.php. So you don't need to add in your app/Config/Filters.php.

Check your filters with the spark routes command.