Two-Factor Authentication and Passkeys
BugPin can ask for a second step after the password. Each user sets up one or more methods in their profile, and administrators can require two-factor authentication for admins or for everyone. Passkeys also let users sign in without a password.
Sign-in Methods
| Method | What it is | Used for |
|---|---|---|
| Authenticator app | A 6-digit code that changes every 30 seconds (TOTP), from apps such as 1Password, Bitwarden, Google Authenticator or Microsoft Authenticator | Second step after the password |
| Passkey | A key stored on a device or in a password manager, unlocked with a fingerprint, face or device PIN | Sign-in without a password, or second step after the password |
| Recovery codes | 10 single-use codes created with the first method | Second step when no other method is at hand |
Every method that is set up counts as two-factor authentication. Once a user has at least one, BugPin asks for it after every password sign-in.
Setting Up Two-Factor Authentication
Open the user menu in the bottom left of the Admin Console, choose Profile, and switch to the Security tab.
Adding an authenticator app or a passkey asks for your current password first, as do removing a method and regenerating recovery codes.
Authenticator App
- Next to Authenticator app, click Set up and confirm with your password
- Scan the QR code with your authenticator app. If you can't scan it, enter the key shown below the code
- Click Next and enter the 6-digit code from the app
- If this is your first method, save the recovery codes (see below) and click Done
To turn the authenticator app off, click Turn off and confirm with your password.
Passkeys
- Next to Passkeys, click Add passkey and confirm with your password
- Give the passkey a name that tells you which device holds it, for example "Work laptop", and click Continue
- Follow your browser's prompt to create the passkey
- If this is your first method, save the recovery codes and click Done
You can add several passkeys, for example one per device. Each passkey in the list shows when it was added and last used. Use the pencil icon to rename a passkey and the trash icon to remove it. Removing a passkey asks for your password.
Recovery Codes
BugPin creates 10 recovery codes with your first method and shows them once. Copy or download them and keep them somewhere safe, such as your password manager. Each code signs you in once.
The Recovery codes row shows how many codes are left. Click Regenerate and confirm with your password to replace all codes with 10 new ones. The old codes stop working right away.
When you remove your last method, BugPin deletes the recovery codes as well.
Signing In
With a Password and a Second Step
After the email and password, BugPin asks for the second step. It starts with the authenticator app when one is set up, otherwise with a passkey. Links below the form switch to another method:
- Use your authenticator app: enter the 6-digit code
- Use a passkey: click Use passkey and confirm with your device
- Use a recovery code: enter one of your recovery codes
The second step must be completed within 5 minutes, and after 5 wrong codes the sign-in starts over.
BugPin also counts failed second steps per account, across all sign-in attempts and client addresses. After 10 failed attempts with an authenticator code, a recovery code or a passkey within 15 minutes, the second step is blocked for that account for 15 minutes, and BugPin answers with HTTP 429 and the error TOO_MANY_ATTEMPTS. This protects accounts whose password is known to an attacker. A successful second step resets the count.
With a Passkey Only
On the sign-in page, click Sign in with a passkey and choose your passkey. The passkey replaces both the password and the second step, because it already proves that you have the device and can unlock it.
Requiring Two-Factor Authentication
Administrators decide who must use two-factor authentication under Security → Two-Factor:
| Setting | Effect |
|---|---|
| Off (default) | Two-factor authentication is optional |
| Admins only | Every admin must set up a method |
| All users | Every user must set up a method |
Users covered by the policy who have no method yet see a Set up two-factor authentication dialog after signing in. The Admin Console and the API stay locked until they add an authenticator app or a passkey. While the policy applies, users can't remove their last method.
This includes API tokens (Enterprise Edition): requests with a token that belongs to such a user are refused with HTTP 403 and the error TWO_FACTOR_SETUP_REQUIRED until the user has set up a second factor.
Resetting Two-Factor Authentication
If a user loses access to every method and all recovery codes, an administrator can reset two-factor authentication:
- Go to Users in the Admin Console. Users with two-factor authentication show a 2FA badge
- Click the shield icon next to the user and confirm
This removes the user's authenticator app, passkeys and recovery codes and signs the user out of all sessions. If a policy applies, the user sets up a new method at the next sign-in.
If no administrator can sign in, reset it on the server:
# Docker
docker exec -it bugpin bun run reset-two-factor [email protected]
# Bun installation
bun run reset-two-factor [email protected]
The command does the same as the reset in the Admin Console, including signing the user out of all sessions.
Passkey Requirements
- HTTPS: Browsers allow passkeys only on HTTPS sites and on
localhost - A fixed address: A passkey belongs to the domain name it was created on, for example
bugs.example.com. It doesn't work on another domain or a raw IP address. If you move BugPin to a new domain, users need to add new passkeys - Matching host: BugPin accepts passkey requests only when the address in the browser matches the host the request was sent to or the Application URL under Settings → General. If your reverse proxy rewrites the
Hostheader, set the Application URL to the public address
When the address doesn't match, BugPin answers with "Passkeys only work on the address BugPin is configured for".
How BugPin Stores These Methods
- Authenticator secrets are encrypted with AES-256-GCM using a key derived from the instance's secret key
- A code is accepted for 30 seconds before and after its time window, and each code works only once
- Recovery codes are stored as SHA-256 hashes
- Passkeys are stored as public keys. BugPin never sees the private key