Interface IUserAuthenticationStrong

All Known Subinterfaces:
IUserAuthenticationUI

public interface IUserAuthenticationStrong
Strong authentication, the part of IUserAuthenticationUI for it (CC-SIGNIN-STRONG-POLICY; the design of order 475, the owner's rulings SA-D-1..SA-D-11): a sign-in that completes several server-verified factors - a passkey with user verification, a code of an authenticator app, and in the iiziRun app a biometric device key once the device-key orders have made it live - under a StrongAuthPolicy the operator and the application set.

The supported maximum (CC-FIX-SIGNIN-STRONG-SUPPORTED-MAX): no setting and no call of this interface may ask for more than this build fully supports today, StrongAuthSupport - the factors passkey and totp, so a count of at most 2; the biometric device key is not supported until the device-key orders. A value above it is refused where it is set, with a message naming the value and what is supported: in a setting at the server's start or in its editor, in a raise by its answer, in a step-up by SigninResult.SYSTEM_FAILURE. It is never accepted and capped, and never accepted to fail at a sign-in.

The policy is resolved when it is asked for, from five sources combined the strictest winning field by field (section 2.3 of the design): the server settings ($signIn.strong.*), the server environment's custom application settings (signIn.strong.*), the application's definition in config.iiziServer (strongCount, strongFactors, ...), the application's own moduleApp settings (signIn.strong.*), and what the application's code raises. The application raises and never lowers. For a user the policy binds, a count of 1 or more replaces v5's second-factor rule; v5's signIn.* keys keep their behavior for everyone else.

The sign-in under the policy is the sign-in of IUserAuthenticationSecondFactor with more steps: the first factor - a password, a device token, or a passkey, which counts as the factor passkey - leaves the sign-in held (SigninResult.SUCCESS_SECOND_FACTOR_REQUIRED) until as many different factors as the target are verified, each at most once, the mandatory ones among them. getStrongAuthState(IClientSessionGyro) tells what was verified and what to ask next. A user who lacks an enrolled factor enrolls it in the same held sign-in (beginTotpEnrolment, enrolPasskeySecondFactor); the enrollment of the last one completes the sign-in. No trust waives a factor for a bound user (SA-D-9): not a trusted device, not a device token's trust, not a biometric resume. A recovery code is never a factor: it lets the user reach the enrollment of a replacement, and the sign-in completes when that is enrolled (SA-D-10). A client that cannot do a mandatory factor, or under the strict device rule the count, is answered SigninResult.STRONG_AUTH_CLIENT_REQUIRED before the password; under the flexible rule the client does what it can, never below the policy's floor (SA-D-8).

The proof of a sign-in carries every verified factor (MFAProof.methods); getVerifiedFactors(IClientSessionGyro) reads it.

Author:
Christopher Mindus
  • Method Summary

    Modifier and Type
    Method
    Description
    Gets the effective strong authentication policy of the application of this session: every source combined, the strictest winning field by field, with what the application's code raised.
    Gets where this client session stands under the policy: before a sign-in, the factors this client lacks for one to be possible; while a sign-in is held, the target, the factors verified so far and what to ask next; for a signed-in session, the factors its sign-in verified.
    Gets the factors the sign-in of this session verified: the methods of its proof, strongest first.
    Raises the strong authentication policy of the application from its code, for every sign-in from now on (source S5 of section 2.3 of the design): what is given combines with the other sources, the strictest winning field by field, so the application can require more than the operator set and never less.
    Asks a step-up of a signed-in session, for one action: "this payment needs two factors now" (section 2.3 of the design, the per sign-in step-up).
  • Method Details

    • getStrongAuthPolicy

      StrongAuthPolicy getStrongAuthPolicy(IClientSessionGyro clientGyro)
      Gets the effective strong authentication policy of the application of this session: every source combined, the strictest winning field by field, with what the application's code raised.
      Parameters:
      clientGyro - The Client Session Gyro that is the cause of this request.
      Returns:
      The policy, StrongAuthPolicy.OFF when none is set; a policy whose sources combine into an inconsistent one is logged and answered as OFF here, and the sign-in is refused with SigninResult.SYSTEM_FAILURE (fails closed).
    • getStrongAuthState

      StrongAuthState getStrongAuthState(IClientSessionGyro clientGyro)
      Gets where this client session stands under the policy: before a sign-in, the factors this client lacks for one to be possible; while a sign-in is held, the target, the factors verified so far and what to ask next; for a signed-in session, the factors its sign-in verified.
      Parameters:
      clientGyro - The Client Session Gyro that is the cause of this request.
      Returns:
      The state, StrongAuthState.NONE when the policy binds nobody here.
    • getVerifiedFactors

      Set<String> getVerifiedFactors(IClientSessionGyro clientGyro)
      Gets the factors the sign-in of this session verified: the methods of its proof, strongest first.
      Parameters:
      clientGyro - The Client Session Gyro that is the cause of this request.
      Returns:
      The factors, unmodifiable; empty when the session is not signed in, or its sign-in verified none.
    • raiseStrongPolicy

      String raiseStrongPolicy(StrongAuthPolicy.Source raise)
      Raises the strong authentication policy of the application from its code, for every sign-in from now on (source S5 of section 2.3 of the design): what is given combines with the other sources, the strictest winning field by field, so the application can require more than the operator set and never less. A raise that asks for more than is supported today (a count above StrongAuthSupport.maxCount(), a factor that is not supported) or makes the combined policy inconsistent - say a mandatory factor the operator's factors do not allow - is refused by the answer, and nothing changes: never by an exception, so that an application's start is not killed by its own policy. The raise lives with the loaded application: an application calls this when it starts.
      Parameters:
      raise - What to raise: the keys set are combined, the keys null are left to the other sources; StrongAuthPolicy.Source.NONE drops an earlier raise.
      Returns:
      null when the raise is accepted and in force; otherwise the refusal in plain words, naming the offending value and what is supported, or the consistency rule broken.
      Throws:
      NullPointerException - If raise is null.
    • requestStepUp

      SigninResult requestStepUp(IClientSessionGyro clientGyro, StrongAuthPolicy required)
      Asks a step-up of a signed-in session, for one action: "this payment needs two factors now" (section 2.3 of the design, the per sign-in step-up). When the session's sign-in was authenticated within the last 5 minutes (IUserAuthenticationPasskeys.isRecentlyAuthenticated(IClientSessionGyro)) and verified enough factors for the policy given, the answer is SigninResult.SUCCESS at once. Otherwise the session is held for the factors still missing, as a sign-in is: the answer is SigninResult.SUCCESS_SECOND_FACTOR_REQUIRED, getStrongAuthState(IClientSessionGyro) says what to ask, and the same calls that complete a sign-in complete the step-up (verifySecondFactor, finishPasskeyAssertion); the session stays signed in meanwhile. When the step-up is met the session's authentication time is set and its proof carries the factors, so a second ask within 5 minutes is answered at once.
      Parameters:
      clientGyro - The Client Session Gyro that is the cause of this request.
      required - The policy the action needs, combined with the application's effective policy, the strictest winning; null for the application's policy alone.
      Returns:
      SUCCESS when met now; SUCCESS_SECOND_FACTOR_REQUIRED when held for the missing factors; SigninResult.STRONG_AUTH_CLIENT_REQUIRED when this client cannot do them; SigninResult.SUCCESS_NOT_SIGNED_IN when nobody is signed in; SigninResult.SYSTEM_FAILURE when required asks for more than is supported today or the policies combine into an inconsistent one (SEVERE logged, naming it).