Skip to content

Frontend login

You can access Kirby's login logic from your templates and controllers, which allows you to use all of Kirby's login methods for frontend login forms.

Kirby's Auth class provides the following methods that can be used for authentication. All methods will throw Exceptions if the input is not valid.

Logging in with email and password

$kirby->auth()->login(string $email, string $password, bool $long = false);

This method validates the email and password of the user and logs the user in immediately if the credentials are correct. If the $long parameter is set to true, the user will stay logged in using a "long" session (default = false).

You can find an example how to use this method in our cookbook recipe "Restricting access to your site".

Creating an authentication challenge

$status = $kirby->auth()->createChallenge(string $email, bool $long = false, string $mode = 'login');

This method can be used for passwordless login or password reset.

It creates an authentication challenge (for example by sending an email with a login code). The type of challenge that gets created is determined automatically based on the user's email address and the provided $mode (which can be login or password-reset). The configured challenge priorities are respected.

The $auth->createChallenge() method returns the authentication status object. This object contains all necessary information about the next steps:

$status->challenge(); // for example 'email', 'totp', ...
$status->email();     // email address of the pending authentication
$status->status();    // 'pending' if a challenge is active
$status->toArray();   // all public information combined in an array

Kirby remembers the pending authentication status via the user's session. You can access the status at any time with $kirby->auth()->status().

2FA login

$status = $kirby->auth()->login2fa(string $email, string $password, bool $long = false);

This method is a combination of the login() method and the createChallenge() method: It will first validate the password and then create an authentication challenge (which will be returned in the status object like explained above). The user is only logged in after both steps are done.

Verifying a provided code

Once the user enters the code you requested with the createChallenge() or login2fa() methods, all you need to do is to call the verifyChallenge() method and Kirby will automatically check if the code is correct:

$kirby->auth()->verifyChallenge(string $code);