Admin login security

The admin login of a yf site can ask for a second factor after the password (an authenticator app, a code by e-mail, a passkey, or a recovery code), refuse logins from IP addresses or countries outside the site's rules, and block repeated failed logins. Everything is off until a super-admin turns it on in Settings, tab Admin login; with everything off the login page and the login work exactly as before. Each change is written to the admin wall, failed attempts to the failed-login log (log_admin_auth_fails); no code, secret or recovery code is ever logged.

Two-factor authentication

With admin_2fa.ENABLED on, every admin finds Account / Two-factor authentication (?object=admin_account&action=two_factor) and can set up:

  • Authenticator app (TOTP, RFC 6238: Google Authenticator, Microsoft Authenticator, Aegis, 1Password, ...): the page shows a QR code and the key; the admin types the 6-digit code once to confirm. The secret is stored encrypted with a key derived from YF_SECRET_KEY, so this method needs that constant (32 or more random bytes, outside the web root and outside git: make one with php -r "echo bin2hex(random_bytes(32));"). Keep a copy of the key: without it the stored secrets cannot be read and every admin falls back to recovery codes. A code is accepted 30 seconds before and after its time, and only once.
  • Codes by e-mail: a 6-digit code sent to the account address, valid 10 minutes, single use, at most 5 wrong tries; at most 3 mails in 15 minutes and one per minute. The codes are stored as an HMAC with the site key, so they also need YF_SECRET_KEY. E-mail is only as safe as the mailbox: prefer the app. admin_2fa.METHODS chooses what admins may set up; a factor an admin already has is always asked, whatever it says.
  • Passkeys (WebAuthn: the fingerprint or face of a phone or laptop, Windows Hello, a security key), offered while METHODS holds passkey (the default): see Passkeys.
  • Recovery codes: 10 codes like K7QF-2MXA-9PLD-W3RT, made with the first factor and on demand (with the password), shown once, each usable once. Only their hashes are stored.

After a good password an admin with a factor sees a second form: the code from the app, "E-mail me a code", or a recovery code in the same field. After a wrong code the next try waits 1, 2, 4, 8 ... seconds; five wrong codes send the admin back to the password; ten failed second steps within an hour stop the second step for that admin until the hour is over (MAX_TRIES, MAX_FAILS_ACCOUNT). The step is valid 5 minutes and only from the address that gave the password. With REMEMBER_DEVICE_DAYS above 0 the form has "Remember this device": a signed cookie skips the second factor (never the password) on that browser; a password change, a reset or "Forget all" ends it. The cookie is a bearer token: copied to another browser it works there too until it expires, so keep the number of days low and use "Forget all" when a device is lost.

Adding or replacing a factor while one is set up, removing one and making new recovery codes ask for the password again (five wrong passwords in a session stop these actions for an hour); a replacement also forgets the remembered devices and shows new recovery codes (the old ones stop working). The admin gets an e-mail on every such change and on a reset (NOTIFY_EMAIL); when the address of the account changes, the old address is told. Super-admins who have a factor themselves see every admin's factors on the same page and reset one (they type the admin's login and their own password); the button is also there for an admin who must have 2FA and has none. A super-admin's "log in as" (login_as) does not ask the other admin's second factor: it is written to that admin's wall.

Passkeys

With 2FA on, an admin finds Add a passkey on the 2FA page (passkey is in the default admin_2fa.METHODS; take it out to stop offering them): name it after the device, press Create the passkey, and the browser asks for the fingerprint, face, PIN or security key. An admin may keep up to 10 (one per device); renaming and removing one ask for the password. Adding one while a factor is set up asks for the password, like every other factor change, and the admin gets an e-mail. An extra passkey keeps the recovery codes and the remembered devices; only replacing an authenticator app or the e-mail factor renews them. After the password the second step then shows Use a passkey; recovery codes keep working.

The verifier is part of yf (no library): ES256 and RS256 keys, attestation none (the device maker is not checked), a single-use challenge per form that expires after 5 minutes, the exact origin, the rp id, user presence and the signature counter: a passkey whose counter goes back (a possible clone) is refused and written to the admin wall as important. Synced passkeys (iCloud, Google) always send 0 and are accepted.

  • HTTPS: browsers offer passkeys only on https:// pages (and on http://localhost).
  • rp id (PASSKEY_RP_ID): the domain the passkeys are bound to. Set it (the doctor warns while it is empty, and reports it as critical with logins without the password): empty, it is the host the admin is opened on, which an alias or a proxy can change. A parent domain works for its subdomains (example.com covers admin.example.com). Never an IP address. A passkey works only with the rp id it was set up for; the doctor counts the ones set up for another rp id.
  • Origins (PASSKEY_ORIGINS): the exact addresses the admin is opened on (https://admin.example.com, with the port when it is not the default one), by default the address of the request. Behind a proxy that rewrites the host, list them.
  • User verification (PASSKEY_USER_VERIFICATION): preferred accepts a security key that is only touched; required also wants its PIN or the fingerprint.
  • Without the password (PASSKEY_PASSWORDLESS, off, typed confirmation): the login page gets Log in with a passkey. The browser offers the passkeys it holds for the site; the passkey must verify the admin (PIN, fingerprint), which makes it two factors at once, so the 2FA requirement is met. The password login stays. The IP / country rules, banned IPs and the failed-login limit per IP apply as to passwords; every refusal reads the same ("The passkey was not accepted"), so the page never tells whether a login exists, and counts like a failed second step of that admin (MAX_FAILS_ACCOUNT). Turn on Block repeated failed logins with it (the doctor warns otherwise): its limit per IP is what stops an address that keeps trying. While it is on, adding a passkey always asks for the password (also the first one), and a password change (the admin's own account page, or a super-admin in the admin editor) removes that admin's passkeys, with an e-mail and a wall entry: a passkey must not outlive a password that was changed because it leaked. Were they the admin's only factor, the recovery codes go too and, when 2FA is required, a set-up window opens as after a reset. A passkey added as the first factor while this was off was added without the password, and now logs in alone: after turning this on, review the passkeys (the doctor lists the admins who have such passkeys) or have them removed and added again.

The site doctor (Security) checks HTTPS, an rp id that is not a domain or does not cover the admin address, and passkeys bound to an old rp id. A passkey is a row of admin_2fa (type passkey: the credential id, the public key as PEM, the counter); the WebAuthn user handle is random per admin, never the admin id.

Requiring 2FA

admin_2fa.ENFORCE makes a second factor mandatory for super-admins (group 1), the groups in ENFORCE_GROUPS, or every admin. It needs a typed confirmation. An admin who must have one and has none is refused, and the login page says why. A super-admin's reset (or admin:2fa reset) opens a set-up window: within RESET_SETUP_HOURS (24), until a factor is set, the admin may log in to set one up (each such login is mailed to the admin and written to the wall). A site may also allow a grace period (GRACE_DAYS, 0 by default): during it an enforced admin without a factor still logs in, counted from that admin's first such login. One exception keeps the site reachable: while no active super-admin has a second factor, a super-admin still gets in. In all these cases the session sees only the set-up page, in the bare login layout (no menus, no other admin data, no reset of other admins), until a factor is set.

Set up your own factor, save its recovery codes, then turn enforcement on. In a set-up window or a grace period whoever has the admin's password first can set up a factor in that admin's name (trust on first use): the admin gets an e-mail and the admin wall shows it. Keep these windows short, and ask the admins to set up their factor before you require it.

IP and country rules

admin_login_guard.IP_ALLOW / IP_BLOCK take IPv4 and IPv6 addresses and CIDR ranges (203.0.113.0/24, 2001:db8::/32); COUNTRY_ALLOW / COUNTRY_BLOCK take ISO country codes (DE, UA, US). They work like the per-account lists of the user side (manage_security), for the admin login of the whole site: an allow list wins over its block list, IP rules over country rules (an allowed address skips the country check; an address outside a non-empty IP allow list is refused whatever its country). They are checked before the password, so a refused login reads nothing from the admin table. The address is REMOTE_ADDR; behind a load balancer or CDN list it in Trusted proxies (client_utils.TRUSTED_PROXIES) first, then the visitor address from its headers counts, and only from it. Without that, an allow list sees the proxy's address and refuses everybody.

The country comes from the web server's GeoIP module ($_SERVER['GEOIP_COUNTRY_CODE']), from the header a trusted proxy sends (COUNTRY_SERVER_VAR, e.g. Cloudflare's CF-IPCountry), or from the PHP geoip extension. When it cannot be found, COUNTRY_UNKNOWN decides (refuse by default). Behind a trusted proxy the web server's GeoIP variable describes the proxy, so it is not used there: name the proxy's country header instead. The site doctor says when no source answers and when a list holds an entry that is not an address, range or country code (IPv4-mapped IPv6 such as ::ffff:c000:201 counts as the IPv4 address).

The rules are checked at login only: a session that is already logged in keeps working when the rules change (the session is bound to its IP by SESSION_LOCK_TO_IP). The Settings page refuses rules that would refuse the admin who saves them.

Failed logins

auth_admin.BLOCK_FAILED_LOGINS refuses further tries, without checking the password, after BLOCK_FAILED_MAX_LOGIN (5) failed logins of one login name or BLOCK_FAILED_MAX_IP (10) from one address within BLOCK_FAILED_TTL (an hour). Someone who knows a login can keep it blocked that way; 2FA or an IP allow list protect better than very low limits. Refusals by the IP and country rules and failed second steps are logged without the login name, so they never count towards the limit of a login.

Locked out

  • Lost the phone (or the security key): use a recovery code, or have another super-admin reset your 2FA.
  • Nobody can log in: on the server, with the yf console tool (.dev/console/yf.php of the framework, run inside the project), php .dev/console/yf.php admin:2fa status shows every admin's factors and the rules, and php .dev/console/yf.php admin:2fa reset <login> --yes removes the factors of one admin (who then logs in with the password, and sets up a new factor when 2FA is required).
  • The IP or country rules lock everybody out: add define('YF_ADMIN_LOGIN_BREAK_GLASS', true); to .dev/override.php or the admin entry script. It turns off the IP and country rules and every second factor for all admins; each login made under it goes to the admin wall and the site doctor shows it as critical. Fix the rules, then remove the line.

Sites with their own login page

The second step and the set-up page of a session that must set up a factor are drawn by login_form::_admin_login_form() inside the admin login template. A site that overrides that method or the template adds them itself (and, for passkey logins without the password, $tfa->passwordless_form() after a form of its own):

public function _admin_login_form()
{
    $tfa = _class('admin_2fa', 'classes/auth/');
    if (($page = $tfa->enrol_page() ?: $tfa->login_step_form()) !== '') {
        return $page;
    }
    return $tfa->login_notice() . parent::_admin_login_form();
}