Class SignInSettingsRules

java.lang.Object
com.iizix.server.user.mfa.SignInSettingsRules

public final class SignInSettingsRules extends Object
The rules of the sign-in settings an administrator edits in ServerAdmin's Sign-in page (CC-SERVERADMIN-SIGNIN-PAGE, order 510; the design of the survey CC-SURVEY-SERVERADMIN-SIGNIN-SETTINGS, its sections 4.2 to 4.6): what each setting means, its range and its default, how it is written to the configuration (with the property class iiziGo's catalog names, so the file keeps the form iiziGo reads and writes), which change lowers the administrators' protection (guard G2), which change would lock the administrators out (guard G1: a second step required of them while ServerAdmin's own application offers no method they could set up), which change has a consequence a dialog states before it is made (guard G3), and the one audit line per changed key. ServerAdmin's page binds its fields to these rules and holds none of its own, so that a later level (an environment's policy, a group's) or a later key is added here once.

The levels. SignInSettingsRules.Level.SERVER: a property of the server settings ($signIn.*, SignInPolicy.SERVER_PREFIX and ServerSettings). SignInSettingsRules.Level.ADMIN_POLICY and SignInSettingsRules.Level.USER_POLICY: a property of the two password policy containers $admin and $user (PolicyProps). SignInSettingsRules.Level.ENVIRONMENT: an entry of a server environment's custom application settings (customApp, the passkey keys of PasskeySettings), chosen per environment. An application's own values (signIn.* in its module project, in its jar) are not edited here: they are shown read only with their source.

Values. Every value crosses this class as a text: the text written to the configuration, or null for a setting that is absent (its default applies; writing null removes the key). A choice is its number ("0", "1", "2"), a flag is "true" or "false", a number is its digits, the methods are the names separated by commas, in the order of SignInPolicy.ALL_METHODS.

What a change does to sessions already signed in: nothing. Every setting here is read where it is used (SignInPolicies, PasskeySettings, ServerSettings), so a change applies at the next sign-in or the next check without a restart; the password policies are cached in ServerSettings and the page drops the caches when it saves (ServerSettings.dropPasswordPolicies()).

The strong authentication policy (CC-SERVERADMIN-STRONG-AUTH, order 551): the six server-level keys $signIn.strong.* are settings of SignInSettingsRules.Kind.STRONG - each value is checked by the policy's own parser (StrongAuthPolicy.Source.of(String, String, String, String, String, String, String): a value outside its range or above the supported maximum is refused where it is typed, naming what is supported), count and floor are written as integers and the rest as texts (the classes iiziGo's catalog names), and the six are read and written together as one source (strongSource(ServerSettings), writeStrong(ServerSettings, StrongAuthPolicy.Source)). The guards of the strong keys are StrongAuthGuards'; a change that lowers the strength (strongLowers(StrongAuthPolicy.Source, StrongAuthPolicy.Source)) is a G2 change.

No setting here is a secret today. SignInSettingsRules.Setting.secret exists for the keys to come (the sign-in providers' secrets): the audit line of a secret says that it changed, never its value.

Author:
Christopher Mindus
  • Field Details

    • MAX_VERIFICATION_DAYS

      public static final int MAX_VERIFICATION_DAYS
      The most days an e-mail address may stay unverified: 3650 (iiziGo's catalog range).
      See Also:
    • MAX_SUPPORT_LENGTH

      public static final int MAX_SUPPORT_LENGTH
      The most characters of the support contact: 200.
      See Also:
    • MIN_PASSWORD_LENGTH

      public static final int MIN_PASSWORD_LENGTH
      The least and the most minimum length of a password: 4 (below it PolicyProps.getPasswordMinLength() answers the default) and 128.
      See Also:
    • MAX_PASSWORD_LENGTH

      public static final int MAX_PASSWORD_LENGTH
      The least and the most minimum length of a password: 4 (below it PolicyProps.getPasswordMinLength() answers the default) and 128.
      See Also:
    • MAX_HISTORY

      public static final int MAX_HISTORY
      The most passwords a history keeps: 100.
      See Also:
    • MAX_DOMAIN_LENGTH

      public static final int MAX_DOMAIN_LENGTH
      The most characters of a domain name: 253.
      See Also:
    • MAX_RP_NAME_LENGTH

      public static final int MAX_RP_NAME_LENGTH
      The most characters of a relying party name: 64 (WebAuthn truncates longer ones).
      See Also:
    • SERVER_SETTINGS

      public static final List<SignInSettingsRules.Setting> SERVER_SETTINGS
      The settings of the server level, in the page's order.
    • ADMIN_POLICY_SETTINGS

      public static final List<SignInSettingsRules.Setting> ADMIN_POLICY_SETTINGS
      The settings of the administrators' password policy, in the page's order.
    • USER_POLICY_SETTINGS

      public static final List<SignInSettingsRules.Setting> USER_POLICY_SETTINGS
      The settings of the users' password policy, in the page's order.
    • ENVIRONMENT_SETTINGS

      public static final List<SignInSettingsRules.Setting> ENVIRONMENT_SETTINGS
      The passkey settings of an environment, in the page's order.
    • STRONG_SETTINGS

      public static final List<SignInSettingsRules.Setting> STRONG_SETTINGS
      The six keys of the strong authentication policy, in the order of StrongAuthPolicy.KEYS.
    • STRONG_PREFIX

      public static final String STRONG_PREFIX
      The prefix of the strong keys at the server level: $signIn.strong..
      See Also:
    • ABSENT

      public static final String ABSENT
      The name a text says when a setting is absent (the default applies): "(default)".
      See Also:
    • SOURCE_DEFAULT

      public static final String SOURCE_DEFAULT
      The source of an application's effective value, as the Applications card states it.
      See Also:
    • SOURCE_SERVER

      public static final String SOURCE_SERVER
      The source of an application's effective value, as the Applications card states it.
      See Also:
    • SOURCE_ENVIRONMENT

      public static final String SOURCE_ENVIRONMENT
      The source of an application's effective value, as the Applications card states it.
      See Also:
    • SOURCE_APPLICATION

      public static final String SOURCE_APPLICATION
      The source of an application's effective value, as the Applications card states it.
      See Also:
  • Method Details

    • isDevelopmentMode

      public static boolean isDevelopmentMode()
      Checks if the server runs in development mode, as SignInPolicies decides the default of the administrators' second step (DEV-2FA-1): run from Eclipse, not built into jars.
      Returns:
      true in development mode.
    • current

      public static String current(ServerSettings settings, ServerConfigEnvProps env, SignInSettingsRules.Setting setting)
      Gets the value of a setting as it is written, as a text.
      Parameters:
      settings - The server settings.
      env - The environment, for an environment setting; null otherwise.
      setting - The setting.
      Returns:
      The text of the written value, null when the setting is absent.
    • defaultOf

      public static String defaultOf(SignInSettingsRules.Setting setting)
      Gets the default of a setting as a text: what applies when the setting is absent. The default of the administrators' second step depends on the mode of this server (DEV-2FA-1). The defaults of the passkey entries depend on the server's external URL and on the application they are resolved for; passkeyDefault(SignInSettingsRules.Setting, UnaryOperator, UnaryOperator, String, String) gives them.
      Parameters:
      setting - The setting, not a passkey entry.
      Returns:
      The default as a text, never null (empty for a text that defaults to none).
    • effective

      public static String effective(SignInSettingsRules.Setting setting, String value)
      Gets the value that applies: the written one, or the default when it is absent.
      Parameters:
      setting - The setting, not a passkey entry.
      value - The written value, null for absent.
      Returns:
      The effective value as a text.
    • passkeyDefault

      public static String passkeyDefault(SignInSettingsRules.Setting setting, UnaryOperator<String> environment, UnaryOperator<String> application, String externalURL, String defaultName)
      Gets the default of a passkey entry of an environment: what PasskeySettings.resolve(UnaryOperator, UnaryOperator, String, String) gives the application when the environment does not set it, computed from the current values with the entry left out.
      Parameters:
      setting - The passkey entry.
      environment - The environment's values by key, null for a key it does not set.
      application - The application's values by key, null likewise; k->null for the environment alone.
      externalURL - The server's external URL, null for none.
      defaultName - The relying party name when none is configured (the application's description).
      Returns:
      The default as a text, empty for none.
    • check

      public static String check(SignInSettingsRules.Setting setting, String value)
      Checks a value of a setting that is no passkey entry: its range as the readers clamp it and as iiziGo's catalog states it, the method names, the form of a link. A passkey entry is checked by passkeyProblems(UnaryOperator, UnaryOperator, String, String), through the same code the sign-in runs.
      Parameters:
      setting - The setting.
      value - The value typed, null or blank for "absent, the default applies".
      Returns:
      null when the value is accepted; otherwise why it is refused.
    • strongSource

      public static StrongAuthPolicy.Source strongSource(ServerSettings settings)
      Gets the strong authentication policy the server settings set, as one source: what the six keys say.
      Parameters:
      settings - The server settings.
      Returns:
      The source, StrongAuthPolicy.Source.NONE when no key is set.
      Throws:
      IllegalArgumentException - If a key holds a value the parser refuses (a file of a later version read by this one: the start refuses such a file, so a running server has none).
    • strongValues

      public static UnaryOperator<String> strongValues(StrongAuthPolicy.Source source)
      Gets the texts of a strong source by key with its prefix, as the candidate values of a guard read them.
      Parameters:
      source - The source, null for none.
      Returns:
      The reader: the text of a key the source sets ($signIn.strong.count to its number, the factors comma-separated, an empty mandatory list as a dash), null for a key it does not set.
    • strongLowers

      public static boolean strongLowers(StrongAuthPolicy.Source before, StrongAuthPolicy.Source after)
      Checks if a change of the server's strong policy lowers the administrators' protection (guard G2): the new policy does not raise the old one in every field (StrongAuthPolicy.isRaisedBy(StrongAuthPolicy): a smaller count or floor, a factor allowed anew, a mandatory factor dropped, strict made flexible, everyone narrowed to the administrators). Turning the policy off from on lowers it; turning it on lowers nothing.
      Parameters:
      before - What the server settings set before, StrongAuthPolicy.Source.NONE for nothing.
      after - What they set after.
      Returns:
      true when the change lowers the administrators' protection.
    • writeStrong

      public static Map<SignInSettingsRules.Setting, String> writeStrong(ServerSettings settings, StrongAuthPolicy.Source source) throws PropException
      Writes the server's strong policy: the six keys from a source, each set key with the class iiziGo's catalog names (count and floor as integers, the rest as texts), each unset key removed. Nothing is saved to the file here: the caller saves through the server.
      Parameters:
      settings - The server settings.
      source - The source, null or StrongAuthPolicy.Source.NONE to remove every key.
      Returns:
      What the six keys were before, by key with its prefix (null for absent), in the order of STRONG_SETTINGS.
      Throws:
      PropException - If the container refuses a property.
    • passkeyProblems

      public static Map<String,String> passkeyProblems(UnaryOperator<String> environment, UnaryOperator<String> application, String externalURL, String defaultName)
      Checks the passkey entries of an environment as the sign-in resolves them: every problem PasskeySettings.resolve(UnaryOperator, UnaryOperator, String, String) reports, by the key it is about, so the page shows each on its field and refuses the save - the page cannot accept what the server would drop.
      Parameters:
      environment - The candidate values of the environment by key, null for a key it does not set.
      application - The application's values by key, null likewise; k->null for the environment alone.
      externalURL - The server's external URL, null for none.
      defaultName - The relying party name when none is configured.
      Returns:
      The problems by key (a problem about the external URL under PasskeySettings.KEY_RP_ID), empty when the values are accepted; unmodifiable.
    • lockOut

      public static String lockOut(UnaryOperator<String> server, UnaryOperator<String> environment, UnaryOperator<String> application, String externalURL, String defaultName)
      Checks if candidate settings would lock the administrators out: a second step required of them (for every user, or for the administrators) while ServerAdmin's own application offers no method a user without one can set up - neither an authenticator app nor a passkey with passkeys on and a relying party ID for the environment ServerAdmin runs in. The server would then refuse every administrator's sign-in with SEVERE (UserAuthenticationUIImpl: "requires a second factor and has no method this server can enroll"), and only a file edit could undo it. The policy is resolved as the sign-in resolves it (SignInPolicies, the development default included) and narrowed to what this server can do (UserMFA.METHODS, a passkey where the passkey settings resolve enabled).
      Parameters:
      server - The candidate server values by key ($signIn.*), null for absent.
      environment - The candidate values of ServerAdmin's environment by key, null for absent.
      application - ServerAdmin's own values by key (signIn.* of its module project and signIn.passkey.* of its custom settings), null for absent; k->null when it sets nothing.
      externalURL - The server's external URL, null for none.
      defaultName - The relying party name when none is configured.
      Returns:
      null when the administrators can still sign in; otherwise why the change is refused.
    • lowersProtection

      public static boolean lowersProtection(SignInSettingsRules.Setting setting, String oldValue, String newValue, String secondFactor, String administrators)
      Checks if a change lowers the administrators' protection (SAS-D-6): their second step goes from required to not required (the administrators' choice set to "as every user" while every user's is lower, or every user's lowered while the administrators follow it); more days a device is trusted; staying signed in turned on or kept for more days; the administrators' password policy weakened. Raising protection is never guarded. The values compared are the effective ones (an absent value is its default, the administrators' default by the mode of this server).
      Parameters:
      setting - The setting that changes.
      oldValue - Its written value before, null for absent.
      newValue - Its written value after, null for absent.
      secondFactor - The written value of SignInSettingsRules.Setting.SECOND_FACTOR as it is (the one of the two that does not change), null for absent; for the two second-step settings.
      administrators - The written value of SignInSettingsRules.Setting.SECOND_FACTOR_ADMINISTRATORS as it is, null for absent; for the two second-step settings.
      Returns:
      true when the change lowers the administrators' protection.
    • adminFactor

      public static SignInPolicy.SecondFactor adminFactor(String secondFactor, String administrators)
      Gets the administrators' effective second step from the two written choices.
      Parameters:
      secondFactor - The written $signIn.secondFactor, null for absent.
      administrators - The written $signIn.secondFactorAdministrators, null for absent.
      Returns:
      What the policy would say for an administrator.
    • consequence

      public static SignInSettingsRules.Consequence consequence(SignInSettingsRules.Setting setting, String oldEffective, String newEffective)
      Gets the consequence a dialog states before a change is made, where there is one: the relying party ID changes (the old passkeys stop working), staying signed in is turned off (every device that stays signed in is signed out at its next use), the trust days become 0 (no device is trusted any more).
      Parameters:
      setting - The setting that changes.
      oldEffective - Its effective value before (the default applied, for a passkey entry passkeyDefault(SignInSettingsRules.Setting, UnaryOperator, UnaryOperator, String, String) applied).
      newEffective - Its effective value after, likewise.
      Returns:
      The consequence, null for none.
    • write

      public static String write(ServerSettings settings, ServerConfigEnvProps env, SignInSettingsRules.Setting setting, String value) throws PropException
      Writes a setting to its container: an integer as an IntProp, a flag as a BoolProp, a text as a StringProp - the classes iiziGo's catalog names, so the file keeps the form iiziGo reads - and a passkey entry into the environment's map. A null or blank value removes the key, so the default applies. The methods are written normalized: the names in the order of SignInPolicy.ALL_METHODS, separated by ", ". Nothing is saved to the file here: the caller saves through the server, and drops the password policy caches when a policy changed.
      Parameters:
      settings - The server settings.
      env - The environment, for an environment setting; null otherwise.
      setting - The setting.
      value - The value as a text, null or blank to remove the key.
      Returns:
      The written value before the change as a text, null when it was absent.
      Throws:
      PropException - If the container refuses the property.
      IllegalArgumentException - If the value does not pass check(SignInSettingsRules.Setting, String), or an environment setting has no environment.
    • auditLine

      public static String auditLine(SignInSettingsRules.Setting setting, String environment, String oldValue, String newValue, String administrator, boolean lowers)
      Builds the audit line of a changed key: "Sign-in setting $signIn.trustDeviceDays changed from 30 to 7 by iiziAdmin (ServerAdmin)", with "(default)" for an absent value, the environment named for an environment entry, and never the value of a secret.
      Parameters:
      setting - The setting.
      environment - The environment's name for an environment entry, null otherwise.
      oldValue - The written value before, null for absent.
      newValue - The written value after, null for absent.
      administrator - The administrator's user ID.
      lowers - Whether the change lowers the administrators' protection (said in the line).
      Returns:
      The line.
    • audit

      public static String audit(SignInSettingsRules.Setting setting, String environment, String oldValue, String newValue, String administrator, boolean lowers)
      Logs the audit line: INFO, WARNING when the change lowers the administrators' protection.
      Parameters:
      setting - The setting.
      environment - The environment's name for an environment entry, null otherwise.
      oldValue - The written value before, null for absent.
      newValue - The written value after, null for absent.
      administrator - The administrator's user ID.
      lowers - Whether the change lowers the administrators' protection.
      Returns:
      The line logged.
    • effectiveOf

      public static SignInSettingsRules.Effective effectiveOf(SignInSettingsRules.Setting setting, ServerSettings settings, AppFactory app)
      Gets the effective value of a server-level setting for an application and its source, as SignInPolicy.resolve(PropCnr, PropCnr) decides it: the application's own value when it sets one, the server's when it sets one, the default otherwise.
      Parameters:
      setting - A server-level setting of the policy (the second step, the methods, the trust days, account creation, the verification days, the links).
      settings - The server settings.
      app - The application.
      Returns:
      The effective value and its source.
    • effectiveRpId

      public static SignInSettingsRules.Effective effectiveRpId(AppFactory app)
      Gets the effective relying party ID of an application and its source: the application's own entry, the environment's, or the default (the host of the server's external URL); the source is SOURCE_DEFAULT as well when the resolved settings offer no passkeys.
      Parameters:
      app - The application.
      Returns:
      The effective relying party ID (empty when passkeys are not offered) and its source.