Passwords, two-factor and passkeys
Every account signs in with an email address and a password, and can add an authenticator app (two-factor codes), passkeys, or both. This page explains each method, how long you stay signed in, how to sign other devices out, and what to do when an administrator is locked out. Your own settings are under Settings › Security.
Passwords
Section titled “Passwords”- At least 8 characters. There are no other composition rules.
- At most 72 bytes, the limit of the bcrypt hash Aperture stores. A longer password is refused.
- Only the bcrypt hash is stored, never the password.
To change your password, open Settings › Security, fill in Current password, New password and Repeat new password under Change password, and click Update password. Every other browser signed in to your account is signed out; the one you are using stays signed in.
There is no “forgot password” e-mail. The sign-in page says so: an administrator sets a new password for you under Users (see Change a user).
Two-factor authentication
Section titled “Two-factor authentication”Two-factor authentication adds a 6-digit code from an authenticator app (Google Authenticator, Authy, 1Password and similar) to the password. Aperture uses standard TOTP codes that change every 30 seconds.
Turn it on
Section titled “Turn it on”- Open Settings › Security. Next to Two-factor authentication, click Set up.
- Scan the QR code with your authenticator app, or type the secret shown below it. The entry is named Aperture NVR with your email address.
- Enter the 6-digit code the app shows and click Enable two-factor.
- Aperture shows 10 recovery codes. Save them somewhere safe, then click Done.
The row then reads “On — a one-time code is required when you sign in on a new device.”
Recovery codes
Section titled “Recovery codes”Recovery codes look like ABCD-EFGH. Each one works once, in place of an authenticator code, in the same Authentication code field at sign-in. Upper or lower case does not matter.
They are shown only at setup. To get a fresh set, turn two-factor off and set it up again; that also needs a new scan in your authenticator app.
Sign in with a code
Section titled “Sign in with a code”After the password, Aperture asks for the Authentication code. Enter the current code (or a recovery code) and click Verify. You have 5 minutes after the password step; after that, sign in again from the start.
Trust this device is ticked by default: “Don’t ask for a code when I sign in on this browser again.” See Trusted devices.
Turn it off
Section titled “Turn it off”Click Turn off, confirm with a current authenticator code or your password, and click Turn off. Turning two-factor off, or setting it up again, forgets every trusted device of your account.
Set it up again
Section titled “Set it up again”The app offers Set up only while two-factor is off, so to move to a new authenticator app, turn two-factor off and set it up again. Through the API, POST /api/v1/auth/2fa/setup on an account that has two-factor on needs the same confirmation as turning it off: a body of {"code":"<current code>"} or {"password":"<password>"}. Without it the answer is 401 with the code reauth_required, and the current authenticator keeps working. With it, the old authenticator stops working at once, trusted devices are forgotten, and two-factor stays off until you confirm a code from the new one with POST /api/v1/auth/2fa/enable. The activity log records this as auth.2fa_disabled with “setup started again”.
Passkeys
Section titled “Passkeys”A passkey signs you in with your fingerprint, face or device PIN, with no email, password or code. Aperture uses WebAuthn passkeys stored in your device, your password manager or a security key.
Add a passkey
Section titled “Add a passkey”- Open Settings › Security.
- Under Passkeys, click Add passkey and follow your browser’s prompt.
Each passkey is listed as “Passkey” with the date it was added and last used. Remove one with its bin button (Remove passkey). Removing a passkey does not sign out any session.
If the browser reports “This device already has a passkey for your account.”, that authenticator is already registered.
Sign in with a passkey
Section titled “Sign in with a passkey”On the sign-in page, click Sign in with a passkey and choose the passkey your browser offers. A passkey counts as a second factor: Aperture does not ask for an authenticator code after it, and it marks the browser as a trusted device.
Aperture asks for a discoverable passkey at sign-in. Most phones, computers and password managers create those. A security key that stores no discoverable credential can be registered but will not be offered at sign-in.
What passkeys need
Section titled “What passkeys need”A passkey is bound to the host name it was created on. Aperture derives the WebAuthn relying-party ID from the host the browser used, without the port (internal/api/webauthn_handlers.go, webAuthn). So:
- a passkey made at
https://nvr.example.comworks only atnvr.example.com; - if you change the host name, register your passkeys again;
- behind a proxy, the proxy must pass the original
Hostheader and sendX-Forwarded-Proto: https. Caddy does both by default; for nginx addproxy_set_header Host $host;andproxy_set_header X-Forwarded-Proto $scheme;. Aperture believesX-Forwarded-Protoonly from a trusted proxy: one on the same machine is trusted by default, one on another machine must be listed inAPERTURE_TRUSTED_PROXIESor passkey sign-in through it fails (see Client addresses).
Trusted devices
Section titled “Trusted devices”A browser that has completed a second factor (an authenticator code with Trust this device ticked, or a passkey) is remembered as a trusted device. The next password sign-in from that browser skips the code.
- A trusted device stays trusted for 365 days after it was last used, and each use extends it.
- Signing out keeps the trust: the next sign-in there needs the password, not the code.
- Single sign-on reuses an existing trusted device but does not create one.
- Trust ends when you sign that device out from Signed-in devices, use Sign out all others (for the other devices), turn two-factor off or set it up again, or when an administrator disables your account.
How long you stay signed in
Section titled “How long you stay signed in”Sessions are stored on the server. The browser holds a random 256-bit token in the aperture_session cookie; the database keeps only its SHA-256 hash, so a copy of the database cannot be replayed as a sign-in.
| Limit | Value |
|---|---|
| Signed out after this long without use | 90 days |
| Signed out this long after sign-in, used or not | 365 days |
| How often use is written back | At most once an hour |
The constants are sessionIdle, sessionMax and sessionTouchStep in internal/api/sessions.go. The cookie is HttpOnly and SameSite=Lax, and it is marked Secure when APERTURE_PUBLIC_URL starts with https://.
Your role, name and disabled state are read from the database on every request, so a role change or a disabled account takes effect immediately, not when a cookie expires.
Signed-in devices
Section titled “Signed-in devices”Settings › Security › Signed-in devices lists every browser signed in to your account: the device (guessed from the browser’s user agent), Last active, IP address and when it Signed in. Your current browser is marked This device; a browser that skips the code shows Trusted. “Last active” is coarse because use is written back at most hourly.
- The bin button on another device (“Sign this device out and forget it”) ends that session and forgets its trust, so a lost or sold device needs the full sign-in, code included.
- The bin button on This device signs you out here.
- Sign out all others ends every other session and forgets every other trusted device.
To sign out normally, open the user menu in the top bar and choose Sign out.
What ends sessions
Section titled “What ends sessions”| Event | Sessions | Trusted devices |
|---|---|---|
| Sign out | This browser | Kept |
| Removing a device from Signed-in devices | That device | That device forgotten |
| Sign out all others | All others | All others forgotten |
| Changing your own password | All others | Kept |
| An administrator sets a new password for you | All | Kept |
| Turning two-factor off, or setting it up again | Kept | All forgotten |
| An administrator disables the account | All | All forgotten |
| The account is deleted | All | All |
| 90 days unused, or 365 days after sign-in | That session | Not affected |
Disabling an account also revokes the share links it created and stops its notifications; deleting it removes its share links. See Disable or delete an account.
API tokens are separate from sessions; see The API and tokens.
Failed sign-ins and rate limits
Section titled “Failed sign-ins and rate limits”Aperture has no account lockout. Every failed attempt is written to the activity log as auth.login_failed with the reason (wrong password, wrong code, disabled account, or for single sign-on an email address the provider has not verified, see Verified email addresses).
Requests made before signing in are rate-limited per client address: a burst of 30, then 10 per second (internal/api/limit.go). Beyond that the API answers 429 with Retry-After: 1. That slows guessing but does not stop it, which is one reason not to expose Aperture directly to the internet; see Security model and hardening.
Recover a locked-out administrator
Section titled “Recover a locked-out administrator”Try these in order:
- Another administrator can set a new password for you under Users (see Change a user). This does not turn off your authenticator.
- Lost authenticator: use one of your recovery codes, sign in from a trusted device (password only), or sign in with a passkey. Then turn two-factor off and set it up again.
- No other way in: create a new administrator from the server itself with the local CLI token. It is a full administrator credential, readable only by root, in
/var/lib/aperture/data/cli.token(or yourAPERTURE_DATA_DIR).
TOKEN=$(sudo cat /var/lib/aperture/data/cli.token)curl -s -X POST http://127.0.0.1:8971/api/v1/users \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"email":"recovery@example.com","name":"Recovery","role":"admin","password":"<temporary password>"}'Sign in with that account; Aperture asks it to choose a new password first. There is no way to reset another account’s authenticator from the app: if the old account cannot be recovered, delete it under Users and add it again. Delete the recovery account when you are done.
The same token can set a new password for an existing account with PUT /api/v1/users/<id> and a body of {"password":"<new password>"}; list the ids with GET /api/v1/users.
Troubleshooting
Section titled “Troubleshooting”Sign-in does not stick on a plain-HTTP address. APERTURE_PUBLIC_URL starts with https://, so the session cookie is marked Secure, and you are using a plain-HTTP address. Browsers drop secure cookies on http:// (except localhost). Use the HTTPS address, or set APERTURE_PUBLIC_URL to match how you open Aperture.
Every change fails with “cross-origin request blocked”. Your reverse proxy replaces the Host header, so the browser’s Origin no longer matches it. Pass the original host through (nginx: proxy_set_header Host $host;). See Security model and hardening.
The passkey button is missing. The page is not in a secure context. Open Aperture over HTTPS or on localhost.
A passkey that worked yesterday is not offered. You opened Aperture under a different host name than the one the passkey was created on.
“Incorrect code. Try again, or use a recovery code.” Check that the clock on your phone is set automatically. Codes are accepted for about one 30-second step either side of the server’s time, so the server’s clock matters too.
Related: Users, roles and camera access, Single sign-on, Security model and hardening.