Interface IUserAuthenticationStrong
- All Known Subinterfaces:
IUserAuthenticationUI
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 TypeMethodDescriptiongetStrongAuthPolicy(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.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.getVerifiedFactors(IClientSessionGyro clientGyro) 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.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).
Method Details
getStrongAuthPolicy
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.OFFwhen none is set; a policy whose sources combine into an inconsistent one is logged and answered asOFFhere, and the sign-in is refused withSigninResult.SYSTEM_FAILURE(fails closed).
getStrongAuthState
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.NONEwhen the policy binds nobody here.
getVerifiedFactors
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
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 aboveStrongAuthSupport.maxCount(), a factor that is not supported) or makes the combined policy inconsistent - say a mandatory factor the operator'sfactorsdo 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.NONEdrops 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- Ifraiseis null.
requestStepUp
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 isSigninResult.SUCCESSat once. Otherwise the session is held for the factors still missing, as a sign-in is: the answer isSigninResult.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:
SUCCESSwhen met now;SUCCESS_SECOND_FACTOR_REQUIREDwhen held for the missing factors;SigninResult.STRONG_AUTH_CLIENT_REQUIREDwhen this client cannot do them;SigninResult.SUCCESS_NOT_SIGNED_INwhen nobody is signed in;SigninResult.SYSTEM_FAILUREwhenrequiredasks for more than is supported today or the policies combine into an inconsistent one (SEVERE logged, naming it).