Second factor settings

Second factor settings#

An administrator can require an authenticator app of a standard login - see Second factor. On its own the requirement is recorded and shown; these settings make Querona enforce it: a login that was required to set up an authenticator and has not done so within a grace period is refused at sign-in until it has one.

The rule#

Enforcement is off by default, and nothing changes for any login until it is switched on. With it on, every sign-in of a standard login is judged on three facts:

whether an administrator has required an authenticator of the login - the moment the requirement was recorded, the Required since the login’s profile shows, starts the grace period; a reset records the moment afresh, so the grace period starts over;
whether the login has set up an authenticator - a set-up that was begun and not confirmed with a code does not count;
whether the grace period has passed - the deadline is the recorded moment plus the configured number of days, and a login that is required and has no authenticator is overdue from then on.

A required login without an authenticator signs in as before until the deadline, and is refused after it. A login that has set one up is never affected, and neither is any login that cannot have one - an account using Windows or Microsoft Entra ID integrated authentication, a Spark reverse account or the System account - whatever the settings say. A standard login that a Windows identity of the same name signs in as, over integrated authentication, is held to the rule as well: within the grace period it is admitted, and once overdue it is refused, since an identity carries no code and there is no password a restricted web session could be issued on. A SQL client that signs in so gets the same error 18456 with the reason as one that signs in with a password; the web interface’s Windows sign-in answers the plain The username or password is invalid, and the reason is in the log.

The settings are read at every sign-in, so a saved change takes effect at once, without a restart, for the next sign-in of every login on the node it was saved on. The other nodes of a cluster keep the configuration they read when they started and apply the change when they next start - as for every setting of the Engine configuration. A session, a connection or an access token that is already open is not re-examined: a login that signed in before the deadline keeps working until it signs out, and is held to the rule at its next sign-in.

Settings#

The settings are on the Engine configuration screen: go to ADMINISTER ‣ Engine configuration, click Edit, and find the three second-factor fields after the logon-tracking settings - the same three the table lists, each with a help icon that explains it. Save the screen as usual.

Configuration option	Default value	Requires restart?	Description
Enforce second factor	Disabled	No	Whether a login that is required to have an authenticator is refused once its grace period has passed without one. Disabled, the requirement is recorded and shown but never refuses a sign-in. REST member `enforce`.
Grace period [days]	14	No	How many days a required login may still sign in without an authenticator, counted from the moment the requirement was recorded. 0 to 3650; 0 refuses such a login at its next sign-in. REST member `graceDays`.
Enrolment session [min]	15	No	How long, in minutes, the restricted web session an overdue login is given lasts - long enough to set up the authenticator, and no more. 1 to 1440. REST member `enrolmentSessionMinutes`.

The three settings are also part of the engine configuration that the REST API reads and writes as a whole: GET api/1.0/configuration answers them as the members of secondFactorConfiguration, and PUT api/1.0/configuration stores them with the rest, under the Control server permission. A value outside its range is refused, on the screen and over REST alike, and nothing of the configuration is changed.

What a refused login sees#

The refusal depends on where the login signs in, because only the web interface has a screen to set up an authenticator on.

SQL clients. After the deadline the connection is refused - whether the login signs in with its password or as a Windows identity of the same name - with error 18456, the login failure every SQL Client knows, carrying the reason:

Login failed for user 'x'. Reason: Multi-factor authentication is required for the account, but no authenticator has been set up yet.

The password is checked first, so the reason is given only to a correct password; a wrong one gets the plain login failure, as it always did. The client has nothing to do but sign in elsewhere: the login sets up its authenticator in the web interface and then connects with the code in front of the password. Before the deadline a SQL client sees nothing - there is no message at sign-in.

Web interface. Before the deadline the login signs in as usual and is told in the page header that an authenticator will be required for its account from the deadline, with the days left and a link to its profile. The header shows one notice at a time; when there are several - the license warnings are shown there too - it moves to the next one every thirty seconds, with a counter and buttons to step through them, and each can be dismissed for the session. After the deadline the sign-in still succeeds, but the session is confined to My profile: the navigation is gone, signing out is the only other action, and any other request is refused. The profile says that multi-factor authentication is required for the account and that the login should set up an authenticator to continue, or sign out. The session lasts the configured minutes; when the login confirms its authenticator, it is told to sign in again with the code from the app in front of its password and is signed out.

Programs that request an access token with the login’s password (api/1.0/token) are held to the same rule: after the deadline the token they receive is the restricted one - it carries the scope querona:enrolment, lasts the configured minutes, and reaches only the profile’s calls: the current-user reads, the login’s own second-factor state and enrolment steps, the instance read and the sign-out. Every other call answers 403, and another login’s second-factor state is refused to such a session whatever rights the login holds.

Data API. After the deadline the token endpoint refuses the login (invalid_grant) with the same text a SQL client gets, because a Data API client has no way to set up an authenticator.

Lockout, logon tracking and the audit trail#

The refusal is given after the password was verified, so it is not a failed guess: it does not count toward the failed sign-in lockout of the login and origin, and the correct password clears the count as any successful check does. A refused overdue login can therefore try again as soon as it has set up its authenticator, however many times it was refused before.

It is a failed logon all the same, on every path including the Data API: logon tracking records it as a failed attempt for the login, and the refusal is audited as a failed login like any other - the event of a refused SQL connection, by password or by Windows identity, and of a refused Data API token request carries the reason as its statement; the event of the web interface’s refused Windows sign-in carries the plain login failure, and the reason is in the log alone - see Logging & diagnostics.

What is not covered#

The rule is applied when a login signs in, never to what is already open. A web session opened before the deadline is not ended when the deadline passes; it keeps working until the login signs out, and only the next sign-in is confined to the profile. The same holds for a SQL connection and an access token issued before the deadline.