đź‘€ Get a glimpse of Kirby 5 Learn more
Skip to content
    Search by Algolia

    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

    For security, the status object with a pending challenge is also returned if no challenge was available for the user (e.g. if the user doesn't exist or no suitable challenge was found). This is because Kirby would otherwise leak which users exist and which don't, which is a piece of information that could be used by attackers. In debug mode, an Exception will be thrown in this case, but in production it's important to keep this information secret.

    If your code needs to know if a challenge was really created and you know what you are doing, you can override this security feature by calling $status->challenge(false).

    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 Auth->login() method and the Auth->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 Auth->createChallenge() or Auth->login2fa() methods, all you need to do is to call the Auth->verifyChallenge() method and Kirby will automatically check if the code is correct:

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

    Further reading