Appearance
Two-step sign-in
Two-step sign-in adds a second check to a password: a 6-digit code from an authenticator app on the user's phone (Google Authenticator, Microsoft Authenticator, 1Password, or any app that reads a standard otpauth:// QR code). Someone who learns a password still cannot sign in without the phone.
It applies to local accounts, the ones created on the Users page. Single sign-on accounts are not affected: their identity provider decides whether they need a second step, and Raylux never asks them for a code.
It is off by default. Nothing changes for anyone until a user turns it on for their own account or an administrator requires it for every local account.
Turning it on for your own account
- Sign in to Nexus in a browser.
- Open the account menu: the round button with your initial at the bottom of the navigation rail (on a narrow screen, Two-step sign-in next to your name in the menu).
- Choose Two-step sign-in…, then Turn on….
- Enter your password. This confirms it is you before a phone is added to the account.
- Scan the QR code with your authenticator app. If the camera cannot read it, choose Can't scan it? Show the setup key and type the key into the app instead.
- Enter the 6-digit code the app shows, then Turn on.
- Save the recovery codes that appear. There are ten. Each one signs you in once if you lose your phone. They are shown only at this point.
Nothing is on until a code from the app is accepted, so closing the dialog halfway through changes nothing.
Signing in
After your password, the sign-in screen asks for a code. Enter the current code from the app, or one of your recovery codes. This works the same way in the Nexus web pages, in a runtime screen that asks for a sign-in, in Lens, and in Studio (a Two-step sign-in dialog opens after the password).
- A code is accepted once. A code that was already used, even within its own 30 seconds, is refused; wait for the next one.
- The phone's clock may be up to 30 seconds ahead of or behind the gateway's. If codes are always refused, check the time on the phone and on the Nexus server.
- After five wrong codes the sign-in is canceled and you start again from the password. Wrong codes also count toward the sign-in lockout set on Nexus Settings, the same way wrong passwords do.
- The code step is valid for five minutes after the password is accepted.
Using a recovery code uses it up. When you are running low, create a new set: Two-step sign-in… › New recovery codes…, then enter a current code from the app (a recovery code cannot be used for this). The old set stops working.
To turn two-step sign-in off, choose Turn off… and enter a current code or a recovery code. This is not offered while the gateway requires two-step sign-in.
Requiring it for every local account
An administrator with user-management rights can require two-step sign-in for every local account. The setting is on the Users page (at the top of the list) and on Nexus Settings (the Two-step sign-in card):
- Require for local accounts turns it on.
- Make optional turns it back off. Users who already set it up keep it.
The change takes effect immediately. Nobody is signed out and Nexus does not restart. A local user who has not set up an authenticator app is shown the QR code at their next sign-in and has to finish setting it up before they get in, so turning the requirement on locks nobody out.
The Hardened security profile does not include this requirement. It is its own setting: applying or checking the profile never turns it on or off, and a gateway that read as Hardened before keeps reading as Hardened. The hardening checklist recommends it, but you choose.
Before you require it: the first enrollment
While the requirement is on, a local user who has not set up an authenticator app is asked to at their next sign-in, after entering their password. That means whoever signs in first with an unenrolled user's password is the one who sets up the app. If someone other than the user already knows that password, they can enroll first, and the real user is then asked for a code they do not have.
To avoid this:
- Have every user turn on two-step sign-in for their own account (see above) before you require it. Users who are already enrolled are not exposed.
- Turn the requirement on only when the remaining unenrolled accounts are ones you are about to enroll yourselves, or whose passwords you trust.
- If an account is taken over this way, an administrator clears its two-step sign-in (see below). That also ends every session the account holds, and the real user can then set it up themselves. Change the account's password at the same time.
Sessions end when someone enrolls
When a user turns two-step sign-in on, Nexus ends all of that account's other sessions, in every browser, Lens and Studio, so a session opened before the second step existed does not carry on. The session that was used to turn it on stays signed in. The audit log records it as REVOKE_TOKENS, the same entry the Revoke sessions button writes.
When someone loses their phone
If the user still has a recovery code, they sign in with it and then set the app up again on their new phone (turn two-step sign-in off and on again, or, while it is required, ask an administrator to clear it).
If they have no recovery codes left, an administrator clears it for them:
- Open Users and select the user.
- Under Two-step sign-in, choose Clear two-step sign-in… and confirm.
Their authenticator app and recovery codes stop working at once, and every session the account holds is ended (recorded as REVOKE_TOKENS). They sign in with their password alone until they set it up again, which happens at their next sign-in if the gateway requires it. Clearing needs user-management rights and the right to manage that user (you cannot clear it for an account whose role holds capabilities you do not have). Every clear is recorded in the audit log as MFA_ADMIN_RESET.
What is recorded
The audit log records these events, with the user and the address they came from:
| Action | When |
|---|---|
MFA_ENROLL | A user turned it on (from the account menu, or at sign-in). |
MFA_DISABLE | A user turned it off. |
MFA_CODE_FAILURE | A wrong code, or a code refused because of too many wrong codes. |
MFA_RECOVERY_CODE_USED | A recovery code was used. |
MFA_RECOVERY_CODES_REGENERATED | A user created a new set of recovery codes. |
MFA_ADMIN_RESET | An administrator cleared a user's two-step sign-in. |
REVOKE_TOKENS | The account's sessions were ended: when it was turned on, and when an administrator cleared it. |
MFA_POLICY_CHANGE | The requirement for local accounts was turned on or off. |
Where it is stored
- The app's secret is kept in the gateway's secret store (
raylux_secrets.jsonin the data directory, readable only by the account Nexus runs as). It is never written to the users file or a log, and it is never shown again after setup. - The users file (
raylux_users.json) holds only whether an account is enrolled, a salted hash of each unused recovery code, and the last code step used. - A configuration backup carries neither file (see Backup and restore). If
raylux_users.jsonis copied by hand onto a gateway without the matchingraylux_secrets.json, enrolled users can still sign in with a recovery code; otherwise an administrator clears two-step sign-in for them and they set it up again.
For scripts and other API clients
POST /api/auth/login answers an account that signs in with two steps with {"mfaRequired": true, "mfaChallenge": "...", "mfaMethod": "code"} and no token. Send the code to POST /api/auth/mfa/verify with {"challenge": "...", "code": "123456"}; the reply is the normal sign-in reply with the token. A service account used by scripts should be a local account without two-step sign-in, which also means it must not be used while the gateway requires two-step sign-in for every local account.