Class BreakGlassReset

java.lang.Object
com.iizix.server.user.BreakGlassReset

public final class BreakGlassReset extends Object
The break-glass file of the operator (CC-SERVERADMIN-STRONG-AUTH; section 6.3 of the design of order 475, the owner's rulings SA-D-11 (a) and SR-D-4 (a)): when the strong authentication policy has locked the last administrator out - the authenticator app lost with the phone, no recovery code, no other administrator to reset the account - whoever can write the server's conf\ directory (the same person who could edit config.iiziServer, the root of trust of section 3.4) writes the file "reset-second-factor.txt" there, naming ONE account, and restarts the server. At the start, after the database is open and before the first session is admitted (JettyRunConfiguration.onStartServer, right after DevelopmentAdminReset):
  1. that account's strong factors are reset, in one transaction, as the development reset does it: the authenticator app with its recovery codes (MFAStore.remove(Connection, long)), the passkeys (PasskeyStore.removeAll(Connection, long)), every signed-in or trusted device (DeviceTokenStore.revokeAll(Connection,long)); the password and the profile are kept;
  2. the strong policy is WAIVED for that account's NEXT sign-in only (consumeWaiver(String)): after its password the sign-in runs under v5's rules, which on a built server ask an administrator to set a second step up (the enrollment), and every sign-in after that one is under the strong policy again - the waiver is consumed at the first sign-in that verifies the password, never by a wrong password, and is gone at the next start;
  3. one SEVERE names the account, the counts of what was deleted (never a secret) and that the file was deleted;
  4. the file is deleted, whatever happened: a file that names no account, more than one, or an unknown account is reported SEVERE and deleted too, so that nothing lingers in conf\ - a second start does nothing.

Who can use it: only whoever can write conf\. Nothing a request, a page or a setting does writes the file; ServerAdmin never reads it. A built server and a development server read it alike: a lock-out is a production situation.

What an operator does, in plain steps: (1) stop the server; (2) in the server's conf\ directory, beside config.iiziServer, create reset-second-factor.txt holding the account name on one line (lines starting with # are comments); (3) start the server and read the log for the SEVERE line "Break-glass reset ..."; (4) sign in to ServerAdmin with that account's password from a Browser - no code, no passkey is asked this once - and set the second step up when asked; (5) lower or repair the sign-in strength in ServerAdmin's Sign-in page or the application's dialog if it was the policy that locked everyone out. The file is gone after step 3; if the server is stopped before step 4, write it again.

Author:
Christopher Mindus
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    What a start did.
    static final record 
    What a start did, with the account and the count per kind of what went.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    The file in the server's conf\ directory: "reset-second-factor.txt".
  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    Consumes the waiver of an account's next sign-in, if the break-glass reset of this start left one: the caller (the sign-in flow, after the password was verified) runs that one sign-in under v5's rules.
    static boolean
    Checks if any waiver is pending: while one is, the check that refuses a client before the password (which knows no account yet) is skipped, so that the waived administrator reaches the password on a Browser the strict policy would otherwise refuse; every other account is still held to the policy after its password.
    static boolean
    isWaived(String userName)
    Checks if a waiver is pending for an account.
    run(File confDir)
    Runs the break-glass reset at the start of the server: reads the file in the conf\ directory, resets the named account's strong factors, waives its next sign-in, logs SEVERE and deletes the file.
  • Field Details

    • FILE_NAME

      public static final String FILE_NAME
      The file in the server's conf\ directory: "reset-second-factor.txt".
      See Also:
  • Method Details

    • run

      public static BreakGlassReset.Result run(File confDir)
      Runs the break-glass reset at the start of the server: reads the file in the conf\ directory, resets the named account's strong factors, waives its next sign-in, logs SEVERE and deletes the file. A failure is logged and never stops the start.
      Parameters:
      confDir - The server's conf\ directory (where config.iiziServer is), null for none.
      Returns:
      What was done.
    • consumeWaiver

      public static boolean consumeWaiver(String userName)
      Consumes the waiver of an account's next sign-in, if the break-glass reset of this start left one: the caller (the sign-in flow, after the password was verified) runs that one sign-in under v5's rules.
      Parameters:
      userName - The account's user name.
      Returns:
      true when a waiver was pending for the account, and is now consumed; false otherwise.
    • isWaived

      public static boolean isWaived(String userName)
      Checks if a waiver is pending for an account.
      Parameters:
      userName - The account's user name.
      Returns:
      true when its next sign-in is waived.
    • hasPendingWaiver

      public static boolean hasPendingWaiver()
      Checks if any waiver is pending: while one is, the check that refuses a client before the password (which knows no account yet) is skipped, so that the waived administrator reaches the password on a Browser the strict policy would otherwise refuse; every other account is still held to the policy after its password.
      Returns:
      true when at least one account's next sign-in is waived.