Multi-factor authentication and passkeys
Everything here is on the Security tab of My Account (the person icon in the top bar), in this order: Change password, Authenticator app, Passkeys, Sessions and Security notifications. The same cards are on the GeoIP and Fail2Ban consoles.
Signing in
The sign-in page asks for the user name and the password, or offers Sign in with a passkey. With an authenticator app on the account, a second page asks for the six digits the app shows, or one of the recovery codes; a trusted browser skips it, and a passkey never needs it. Five wrong passwords or codes lock the account for fifteen minutes.
After the code, a browser the account has not trusted is asked whether to trust it (see Sessions and trusted browsers).
Changing the password
The current password, the new one twice, at least 12 characters. The browser you change it from stays signed in; every other session of the account ends.
The authenticator app
Time-based one-time codes from an authenticator app. Set up during first-run setup, or later on the Authenticator app card: prove your password, scan the QR code (or type the secret), and type the six digits the app shows. Nothing changes until that first code is accepted, so a set-up abandoned half way leaves the account as it was.
Switching the app on shows recovery codes once. Each signs in once in place of a code, for the day the phone is lost; keep them somewhere other than the phone. The card says how many are left, and with your password you can:
- Make new recovery codes - the earlier ones stop working at once.
- Switch off the app - signing in asks for the password alone again.
Both changes keep the browser you made them from signed in and end every other session.
An administrator can require an app for an account on the Users page. Until it is set up the card says so, and the next sign-in does not let the person past without setting one up. If someone loses their authenticator and their recovery codes, an administrator takes the app away on the Users page, or the break-glass command does it, run on the server or against it:
$ ohm user totp-disable adminPasskeys
Passkeys (WebAuthn) sign you in with your fingerprint, face or device PIN instead of a password, and count as both factors on their own: a passkey sign-in never asks for a code. Add a passkey on the Passkeys card, name it, and remove one with its row's button.
On the sign-in page, Sign in with a passkey appears only where it can work: the server has a passkey set-up and the browser supports it. Where the server has none, the Passkeys card says Passkeys are not available on this server.
A server sets passkeys up by itself when two things hold:
- The console has a fully qualified name: its Public name on the agent's Certificates page (see The console's public name), or a host name with a dot in it. Passkeys are bound to that name, on the console's port and, while a rule publishes the console on port 443, on that port.
- The console's certificate is trusted by browsers and covers that name: a Let's Encrypt certificate, or one you uploaded. On the self-signed certificate passkeys stay off.
The management API's log says which of the two is missing. A passkey belongs to the name it was registered on: changing the public name or the host name later means registering passkeys again.
Passkeys require a secure context, which is why the console serves HTTPS with a self-signed certificate out of the box rather than plain HTTP.
A passkey's relying-party id must be a domain name. The console's certificate carries DNS names only.
Browsing to https://192.0.2.10:5322 will let you sign in with a password and then fail to
register or use a passkey, in a way that looks like a browser problem. Use the host name.
Sessions and trusted browsers
The Sessions card lists every browser signed in to your account: the browser, the address it signed in from, when it signed in and when it was last seen. It marks this browser, and marks trusted the browsers that skip the code at their next sign-in.
A browser becomes trusted on the prompt that follows the code step: Trust this device remembers it for 30 days, and its sign-ins skip the code and send no notification e-mail. Do that only on a device that is yours and that nobody else uses.
- End a session (its row's button) to sign that browser out at its next page. Ending a trusted session also takes the trust away, so its next sign-in asks for the code again.
- Sign out everywhere else ends every session but this one, and stops every other browser skipping the code - including trusted browsers whose sessions have already run out, which the list no longer shows.
- Signing out yourself ends your session but keeps the browser trusted.
An administrator can end every session of an account from the Users page, which also stops all of its browsers skipping the code. A session ends by itself after eight hours without use, and changing an account's role, its reach or its password from the Users page ends all of its sessions.
Security notifications
Where the server mails you about a sign-in from a browser that is not trusted, and about a browser being trusted. The address is the one on the Profile tab; without one you receive nothing.
Serving the console over plain HTTP
The console answers on 5322 with TLS. Plain HTTP is loopback-only, so it is not reachable from
another machine at all. Reaching a console over plain HTTP would cost you
passkeys, because they need a secure context. Use that port only where something else terminates TLS
in front of the console, or over an SSH tunnel where the address in the browser is localhost and
therefore already a secure context.
TOTP works on either, which is why it is what the setup page offers first.
The console's certificate renews itself
ohm install issues the console's certificate for the server's host name, and the bootstrap agent
keeps it current: the Certificate renewal operation on the agent's Maintenance page runs every
day and a few minutes after the agent starts. A Let's Encrypt certificate is renewed thirty days
before it expires, and a self-signed one is reissued when it nears expiry. The console and the
management API are restarted onto the new certificate.
The agent's Maintenance page shows when the renewal last ran and how it went, and Run now runs it at once. See The console's certificate.
Account lockout
Repeated failed sign-ins lock an account, and so do wrong codes typed while setting up an authenticator app, which count toward the same lockout. Clearing that is an administrator action in the console (Unlock in the account's editor on the Users page), or the break-glass command:
$ ohm user unlock adminSign-in failures also feed Fail2Ban, which acts on the address rather than the account.