auth
Set options for login via the Panel and the API
Brute-force protection
The following options configure how fast Kirby's login brute-force protection gets activated and how long it takes until the triggered protection is disabled again.
Number of trials
You can set the number of wrong trials per timeout period (see below) before login gets blocked for the current IP address and user (since v3.2.3). The default setting is 10.
return [
'auth' => [
'trials' => 10
]
];
Timeout
You can also set the timeout in seconds for the period of time against which the number of trials is counted. The default is 3600 (one hour). After the timeout is over, login for the current IP address and user is possible again.
return [
'auth' => [
'timeout' => 3600
]
];
Login methods
The auth.methods
option controls the available login methods for the Panel and the API.
The available options are:
Name | Explanation |
---|---|
password |
Login with email and password (default) |
code |
Passwordless login with just the email address and a code |
password-reset |
Password reset via a code |
You can read more about the options in the guide. The options can be combined like in the following examples.
All login methods except the default password
method need a working email transport configuration. Otherwise verification emails cannot be sent. Find out more about how to configure your email transport.
Login via code
If you want to prevent login via password completely, you can set the login methods option to code
. The default login via password will be disabled.
<?php
return [
'auth' => [
'methods' => 'code'
]
];
![](https://v39.getkirby.com/media/pages/docs/reference/system/options/auth/6328889130-1704284774/login-960x.png)
Login via code & login via password
You can also combine login via code and login via password. The password-reset
method is then no longer available.
The first method in the array will be the default login method.
<?php
return [
'auth' => [
'methods' => ['code', 'password']
]
];
![](https://v39.getkirby.com/media/pages/docs/reference/system/options/auth/06a31f3c26-1704284774/email-and-password-960x.png)
Password reset
To enable the password reset form, you can combine the default password
login method with the password-reset
method:
<?php
return [
'auth' => [
'methods' => ['password', 'password-reset']
]
];
![](https://v39.getkirby.com/media/pages/docs/reference/system/options/auth/8dec9addd1-1704284774/password-reset-960x.png)
Two-step or two-factor authentication
To enable two-step/two-factor authentication for your logins, you can pass the 2fa
option to the password
method in an array.
The default 2fa
mode will ask users for their email and password first and then send a verification email with an additional code that they have to enter afterwards to verify their login.
This is a two-step authentication as it relies on the password to the email account being secure. If you want even more security, you can use auth challenge plugins for challenges like TOTP, SMS or hardware tokens. The login flow is the same, but the additional login code then gets verified by the plugin.
Two-factor/two-step authentication is not compatible with the code
or password-reset
options as logging in via just a code would circumvent the added 2fa
security.
<?php
return [
'auth' => [
'methods' => [
'password' => ['2fa' => true]
]
]
];
![](https://v39.getkirby.com/media/pages/docs/reference/system/options/auth/36a1176c62-1704284774/2fa-960x.png)
Authentication challenges
Once the user requests a login code or a password reset code, an authentication challenge is created. Kirby by default ships with an email challenge where the code is sent via email. Additional challenges can be added by auth challenge plugins.
The challenges can be configured with the following options:
Code timeout
The timeout controls how long a generated login code is valid. The default is 10 minutes.
<?php
return [
'auth' => [
'methods' => ['code', 'password'],
'challenge' => [
'timeout' => 5 * 60 // 5 minutes
]
]
];
Email options
You can customize the sender and the subject of the code emails:
<?php
return [
'auth' => [
'methods' => ['code', 'password'],
'challenge' => [
'timeout' => 5 * 60, // 5 minutes
'email' => [
'from' => 'mail@example.com',
'fromName' => 'My example project',
'subject' => 'Login code'
]
]
]
];
If you want to customize the emails even more, take a look how to customize the email templates in the guide.
Challenge priority
If multiple auth challenges are installed, you can define the priority of the challenges, i.e. which challenges are tried in which order:
<?php
return [
'auth' => [
'challenges' => ['totp', 'email']
]
];
A challenge will be skipped if it isn't available in general or for the user who tries to log in (e.g. a TOTP challenge needs a prior registration, an SMS challenge needs the mobile number etc.).
The email
challenge is always available as it doesn't need additional configuration (only in some cases the SMTP options). It is also enabled by default if no custom priorities are defined.
If none of the configured challenges is available, Kirby will "fake" the last configured challenge to avoid leaking security-relevant information (e.g. whether the user exists). In debug mode, there will be a clear error message instead.
Auth debugging
Any errors during authentication (e.g. invalid email address, wrong password or code, rate limit, errors during code generation or sending...) are by default hidden from the user. The user only gets the message "Invalid login" or "Invalid code". This prevents various attacks such as user enumeration (where an attacker would be able find out which users are registered on a site).
The real errors are logged to PHP's error log. They can be used to find the actual source of a login failure.
If you don't have access to the PHP error log, you can temporarily enable auth debugging to send the real errors to the user:
<?php
return [
'auth' => [
'debug' => true
]
];
Make sure to disable the auth.debug
mode in production! Displaying auth errors on a public server can be a serious security risk because they could leak information to attackers.
In a production environment, please use the PHP error log to debug issues wherever possible.