Interface SecondFactorPolicy

All Known Implementing Classes:

SecondFactorAuthenticationFilter

public interface SecondFactorPolicy

Stands between a user passing their first factor and being signed in.

Every way of signing in that ends in a session -- the form login, a passkey, and a sign-in through another identity provider -- hands the authentication it established to the chain's SessionSignIn rather than storing it. When the chain has a policy, the policy is asked first, and may take the request over: http.mfa(...) installs the one that asks for a one-time code.

A policy that takes a request over must leave it anonymous. Nothing has been stored for the user at this point -- no security context, no changed session id -- and the policy keeps only what it needs to finish later, by calling SessionSignIn.complete(HttpServer.Request, Authentication, boolean, AuthenticationSuccessHandler) once the second factor is in.

Method Summary

Modifier and Type	Method	Description
HttpServer.Response	intercept(HttpServer.Request request, Authentication authentication, boolean rememberMe)	Decides whether authentication, whose first factor has just been accepted, must present a second.
default boolean	requires(Authentication authentication)	Whether authentication is of a user who has a second factor, so that a first factor alone must not make a request theirs.
default void	satisfied(HttpServer.Request request, Authentication authentication)	Told that authentication signed in with two factors presented in one step -- a passkey whose authenticator verified the user -- so that intercept(HttpServer.Request, Authentication, boolean) was not asked.

Method Details

intercept

HttpServer.Response intercept(HttpServer.Request request,
 Authentication authentication,
 boolean rememberMe)
                       throws Exception

Decides whether authentication, whose first factor has just been accepted, must present a second.

Parameters:

rememberMe - whether the user asked to be remembered: to be handed back to SessionSignIn.complete(HttpServer.Request, Authentication, boolean, AuthenticationSuccessHandler), since the request that finishes the sign-in is not the one that asked

Returns:

null to let the sign-in complete now; otherwise the answer to this request -- a redirect to where the second factor is asked for -- with the sign-in left pending

Throws:

Exception

requires

default boolean requires(Authentication authentication)

Whether authentication is of a user who has a second factor, so that a first factor alone must not make a request theirs.

intercept(HttpServer.Request, Authentication, boolean) is for a sign-in that can stop and ask. This is for the ways of presenting a first factor that cannot: credentials sent with every request, which have no second step to send a code in, and a remember-me cookie, which has nobody at the keyboard. Each asks here and refuses the user when the answer is true; see MfaConfigurer for the rule of each mechanism.

A policy that does not say is taken to require one of everybody.

satisfied

default void satisfied(HttpServer.Request request,
 Authentication authentication)

Told that authentication signed in with two factors presented in one step -- a passkey whose authenticator verified the user -- so that intercept(HttpServer.Request, Authentication, boolean) was not asked.

A policy that counts wrong attempts at its own second factor forgets them here: the user has just proved both factors another way, and whatever was counted against them was not theirs. Nothing unless the policy says more.