feat(security): introduce one-time authz code for form-based auth

Author: michalvavrik

docs/src/main/asciidoc/security-authentication-mechanisms.adoc

@@ -217,6 +217,111 @@ The following properties can be used to configure form-based authentication:
 
 include::{generated-dir}/config/quarkus-vertx-http_quarkus.http.auth.adoc[opts=optional, leveloffset=+1]
 
+[[two-factor-auth]]
+==== Two-factor authentication
+
+The form-based authentication mechanism supports two-factor authentication (2FA), with the second-factor being a one-time authorization code.
+
+.Enable two-factor authentication
+[source,properties]
+----
+quarkus.http.auth.form.otac.enabled=true
+quarkus.http.auth.form.otac.request-redirect-path=/authorization-code-form <1>
+----
+<1> Once the one-time authorization code has been generated, redirect to a page with an authorization code form.
+
+When user submit a username and password to the `/j_security_check` POST location, they will get relocated to the `/authorization-code-form` page.
+The `/authorization-code-form` page should allow users to submit the one-time authorization code sent to them.
+
+.Example form for authentication with a one-time authorization code
+[source,html]
+----
+<form action="/j_security_check" method="post"> <1>
+    <label>Authorization code</label>
+    <input type="password" placeholder="Authorization code" name="j_otac" required>
+    <button type="submit">Login</button>
+</form>
+----
+<1> Send the one-time authorization code to the POST location.
+
+Once Quarkus has generated the one-time authorization code, you need to deliver the code to a user by declaring a CDI bean that implements the `io.quarkus.security.spi.runtime.OneTimeAuthorizationCodeSender` interface.
+
+.Example one-time authorization code sender
+[source,java]
+----
+package org.acme.security;
+
+import io.quarkus.mailer.reactive.ReactiveMailer;
+import io.quarkus.security.credential.PasswordCredential;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.quarkus.security.spi.runtime.OneTimeAuthorizationCodeSender;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.ApplicationScoped;
+
+@ApplicationScoped
+public final class AuthorizationCodeMailer implements OneTimeAuthorizationCodeSender {
+
+    @Inject
+    ReactiveMailer reactiveMailer;
+
+    @Override
+    public Uni<Void> send(SecurityIdentity securityIdentity, PasswordCredential credential) {
+        // send the one-time authorization code to the user represented by the security identity
+        String authorizationCode = new String(oneTimeAuthorizationCode.getPassword());
+        var mail = Mail.withText("[email protected]", "Your authorization code", authorizationCode).setFrom("[email protected]");
+        return reactiveMailer.send(mail); <1>
+    }
+
+}
+----
+<1> Use the Quarkus Mailer extension to send the email with the authorization code.
+See the xref:mailer-reference.adoc[Quarkus Mailer Reference documentation] for more information about the mailer.
+
+NOTE: By default Quarkus stores generated authorization codes in memory.
+If you run your application in multiple instances, you need to store the codes in a database, clustered cache or other external storage.
+It is possible to implement custom storage by declaring a CDI bean that implements the `io.quarkus.security.spi.runtime.OneTimeAuthorizationCodeAuthenticator` interface.
+
+==== Password recovery using a one-time authorization code
+
+Instead of using the one-time authorization code feature as the second authentication factor, you can enable using the code as the single authentication factor.
+Users can still authenticate with the username and password, but for example if they forgot a password, they can generate the one-time authorization code to authenticate and use the session for the password recovery.
+
+.Enable two-factor authentication
+[source,properties]
+----
+quarkus.http.auth.form.otac.enabled=true
+quarkus.http.auth.form.otac.request-path=/generate-authorization-code <1>
+----
+<1> Users can generate the one-time authorization code by sending a username (the `j_username` form param) to the `/generate-authorization-code` POST location.
+
+.Example form for requesting the one-time authorization code
+[source,html]
+----
+<form action="/generate-authorization-code" method="post">
+    <label>Username</label>
+    <input type="text" placeholder="Username" name="j_username" required> <1>
+    <button type="submit">Login</button>
+</form>
+----
+<1> Request the one-time authorization code for a user with specified `username`.
+
+.Example form for authentication with the one-time authorization code
+[source,html]
+----
+<form action="/j_security_check" method="post"> <1>
+    <label>Authorization code</label>
+    <input type="password" placeholder="Authorization code" name="j_otac" required>
+    <button type="submit">Login</button>
+</form>
+----
+<1> Send the one-time authorization code to the POST location.
+
+The one-time authorization code is send in the same fashion as described in the <<two-factor-auth>> section of this guide.
+Once users are logged in, you can provide them with a form to change the password.
+
+IMPORTANT: The `/generate-authorization-code` request path may need to access database or execute remote calls depending on the identity provider you are using.
+In order to prevent the Denial-of-service attack, you should use load shedding to avoid system overload.
+
 [[mutual-tls]]
 === Mutual TLS authentication
 

extensions/security/runtime-spi/src/main/java/io/quarkus/security/spi/runtime/OneTimeAuthZCodeAuthenticationRequest.java

@@ -0,0 +1,28 @@
+package io.quarkus.security.spi.runtime;
+
+import io.quarkus.security.credential.PasswordCredential;
+import io.quarkus.security.identity.request.BaseAuthenticationRequest;
+
+/**
+ * The {@link io.quarkus.security.identity.request.AuthenticationRequest} used for one-time authorization code credentials.
+ */
+public final class OneTimeAuthZCodeAuthenticationRequest extends BaseAuthenticationRequest {
+
+    private final PasswordCredential oneTimeAuthorizationCode;
+
+    private OneTimeAuthZCodeAuthenticationRequest(PasswordCredential oneTimeAuthorizationCode) {
+        this.oneTimeAuthorizationCode = oneTimeAuthorizationCode;
+    }
+
+    private OneTimeAuthZCodeAuthenticationRequest(char[] oneTimeAuthorizationCode) {
+        this(new PasswordCredential(oneTimeAuthorizationCode));
+    }
+
+    public OneTimeAuthZCodeAuthenticationRequest(String oneTimeAuthorizationCode) {
+        this(oneTimeAuthorizationCode.toCharArray());
+    }
+
+    public PasswordCredential getCredential() {
+        return oneTimeAuthorizationCode;
+    }
+}

extensions/security/runtime-spi/src/main/java/io/quarkus/security/spi/runtime/OneTimeAuthorizationCodeAuthenticator.java

@@ -0,0 +1,56 @@
+package io.quarkus.security.spi.runtime;
+
+import java.time.Duration;
+
+import io.quarkus.security.credential.PasswordCredential;
+import io.quarkus.security.identity.AuthenticationRequestContext;
+import io.quarkus.security.identity.IdentityProvider;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.smallrye.mutiny.Uni;
+
+/**
+ * Stores generated one-time authorization code and authenticates {@link SecurityIdentity}
+ * based on one-time authorization code. Must be implemented as a {@link jakarta.enterprise.context.ApplicationScoped}
+ * or {@link jakarta.inject.Singleton} CDI bean.
+ */
+public interface OneTimeAuthorizationCodeAuthenticator extends IdentityProvider<OneTimeAuthZCodeAuthenticationRequest> {
+
+    /**
+     * Event data key that the authenticator can optionally set to the one-time authorization code request
+     * absolute URL if redirection to the page where user was before authentication has been triggered is enabled.
+     */
+    String REDIRECT_LOCATION_KEY = "io.quarkus.security.spi.runtime.otac#REDIRECT_LOCATION";
+
+    /**
+     * Stores generated one-time authorization code.
+     * When used in a production, this method encrypts one-time authorization code before it is stored.
+     * Only one one-time authorization code is allowed per user, if user already had generated the one-time authorization
+     * code, invocation of this method must replace previous authorization code with a new one.
+     *
+     * @param securityIdentity {@link SecurityIdentity}
+     * @param oneTimeAuthorizationCode one-time authorization code credential
+     * @param requestInfo contextual information about request to store the code
+     * @return Uni<Void>; never null
+     */
+    Uni<Void> store(SecurityIdentity securityIdentity, PasswordCredential oneTimeAuthorizationCode, RequestInfo requestInfo);
+
+    /**
+     * Authenticates incoming request based on passed one-time authorization code. Expired one-time authorization codes
+     * must result in authentication failures.
+     *
+     * @param oneTimeAuthZCodeAuthenticationRequest authentication request with one-time authorization code credential
+     * @param authenticationRequestContext authentication request context; simplifies blocking operations
+     * @return SecurityIdentity for which the one-time authorization code was generated
+     */
+    Uni<SecurityIdentity> authenticate(OneTimeAuthZCodeAuthenticationRequest oneTimeAuthZCodeAuthenticationRequest,
+            AuthenticationRequestContext authenticationRequestContext);
+
+    /**
+     * Provides contextual information about incoming request to store one-time authorization code.
+     *
+     * @param redirectLocation absolute URL from which request to generate token arrived; nullable
+     * @param expiresIn code expiration; never null
+     */
+    record RequestInfo(String redirectLocation, Duration expiresIn) {
+    }
+}

extensions/security/runtime-spi/src/main/java/io/quarkus/security/spi/runtime/OneTimeAuthorizationCodeSender.java

@@ -0,0 +1,23 @@
+package io.quarkus.security.spi.runtime;
+
+import io.quarkus.security.credential.PasswordCredential;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.smallrye.mutiny.Uni;
+
+/**
+ * An interface responsible for delivering of the one-time authorization code to the user.
+ * This interface should be implemented as {@link jakarta.enterprise.context.ApplicationScoped}
+ * or {@link jakarta.inject.Singleton} CDI bean.
+ */
+public interface OneTimeAuthorizationCodeSender {
+
+    /**
+     * Sends one-time authorization code to the user.
+     *
+     * @param securityIdentity represents user for which one-time authorization code has been requested
+     * @param oneTimeAuthorizationCode one-time authorization code credential
+     * @return {@link Uni}; must not be null
+     */
+    Uni<Void> send(SecurityIdentity securityIdentity, PasswordCredential oneTimeAuthorizationCode);
+
+}

extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/HttpSecurityProcessor.java

@@ -40,21 +40,26 @@
 
 import io.quarkus.arc.deployment.AdditionalBeanBuildItem;
 import io.quarkus.arc.deployment.BeanContainerBuildItem;
+import io.quarkus.arc.deployment.BeanDiscoveryFinishedBuildItem;
 import io.quarkus.arc.deployment.BeanRegistrationPhaseBuildItem;
 import io.quarkus.arc.deployment.GeneratedBeanBuildItem;
 import io.quarkus.arc.deployment.GeneratedBeanGizmoAdaptor;
 import io.quarkus.arc.deployment.SyntheticBeanBuildItem;
+import io.quarkus.arc.deployment.UnremovableBeanBuildItem;
 import io.quarkus.arc.processor.BeanInfo;
 import io.quarkus.builder.item.SimpleBuildItem;
 import io.quarkus.deployment.Capabilities;
 import io.quarkus.deployment.Capability;
 import io.quarkus.deployment.annotations.BuildProducer;
 import io.quarkus.deployment.annotations.BuildStep;
+import io.quarkus.deployment.annotations.Consume;
 import io.quarkus.deployment.annotations.ExecutionTime;
 import io.quarkus.deployment.annotations.Produce;
 import io.quarkus.deployment.annotations.Record;
 import io.quarkus.deployment.builditem.ApplicationIndexBuildItem;
 import io.quarkus.deployment.builditem.CombinedIndexBuildItem;
+import io.quarkus.deployment.builditem.RuntimeConfigSetupCompleteBuildItem;
+import io.quarkus.deployment.builditem.ServiceStartBuildItem;
 import io.quarkus.deployment.builditem.SystemPropertyBuildItem;
 import io.quarkus.gizmo.ClassCreator;
 import io.quarkus.gizmo.DescriptorUtils;
@@ -69,6 +74,8 @@
 import io.quarkus.security.spi.ClassSecurityAnnotationBuildItem;
 import io.quarkus.security.spi.RegisterClassSecurityCheckBuildItem;
 import io.quarkus.security.spi.runtime.MethodDescription;
+import io.quarkus.security.spi.runtime.OneTimeAuthorizationCodeAuthenticator;
+import io.quarkus.security.spi.runtime.OneTimeAuthorizationCodeSender;
 import io.quarkus.vertx.http.runtime.VertxHttpBuildTimeConfig;
 import io.quarkus.vertx.http.runtime.VertxHttpConfig;
 import io.quarkus.vertx.http.runtime.management.ManagementInterfaceBuildTimeConfig;
@@ -80,6 +87,7 @@
 import io.quarkus.vertx.http.runtime.security.HttpAuthorizer;
 import io.quarkus.vertx.http.runtime.security.HttpSecurityRecorder;
 import io.quarkus.vertx.http.runtime.security.HttpSecurityRecorder.AuthenticationHandler;
+import io.quarkus.vertx.http.runtime.security.InMemoryOneTimeAuthZCodeAuthenticator;
 import io.quarkus.vertx.http.runtime.security.MtlsAuthenticationMechanism;
 import io.quarkus.vertx.http.runtime.security.PathMatchingHttpSecurityPolicy;
 import io.quarkus.vertx.http.runtime.security.VertxBlockingSecurityExecutor;
@@ -97,22 +105,50 @@ public class HttpSecurityProcessor {
     private static final DotName BASIC_AUTH_ANNOTATION_NAME = DotName.createSimple(BasicAuthentication.class);
     private static final String KOTLIN_SUSPEND_IMPL_SUFFIX = "$suspendImpl";
 
+    @Produce(ServiceStartBuildItem.class)
+    @Consume(RuntimeConfigSetupCompleteBuildItem.class)
     @BuildStep
-    @Record(ExecutionTime.STATIC_INIT)
-    AdditionalBeanBuildItem initFormAuth(
-            HttpSecurityRecorder recorder,
-            VertxHttpBuildTimeConfig buildTimeConfig,
-            BuildProducer<RouteBuildItem> filterBuildItemBuildProducer) {
-        if (buildTimeConfig.auth().form().enabled()) {
-            if (!buildTimeConfig.auth().proactive()) {
-                filterBuildItemBuildProducer
-                        .produce(RouteBuildItem.builder().route(buildTimeConfig.auth().form().postLocation())
-                                .handler(recorder.formAuthPostHandler()).build());
+    @Record(ExecutionTime.RUNTIME_INIT)
+    void initFormAuthPathHandlers(VertxWebRouterBuildItem vertxWebRouterBuildItem, HttpSecurityRecorder recorder,
+            VertxHttpBuildTimeConfig httpBuildTimeConfig, VertxHttpConfig httpConfig,
+            BeanContainerBuildItem beanContainerBuildItem,
+            BeanDiscoveryFinishedBuildItem beanDiscoveryResult) {
+        var authBuildTimeConfig = httpBuildTimeConfig.auth();
+        if (authBuildTimeConfig.form().enabled()) {
+            var httpRouter = vertxWebRouterBuildItem.getHttpRouter();
+            if (!authBuildTimeConfig.proactive()) {
+                recorder.formAuthPostHandler(httpRouter, httpConfig);
+            }
+            if (authBuildTimeConfig.form().oneTimeAuthZCodeEnabled()) {
+                recorder.oneTimeAuthZCodeRequestHandler(httpRouter, httpConfig, beanContainerBuildItem.getValue());
+                DotName codeSenderInterfaceName = DotName.createSimple(OneTimeAuthorizationCodeSender.class);
+                if (beanDiscoveryResult.beanStream().stream().noneMatch(bi -> bi.hasType(codeSenderInterfaceName))) {
+                    throw new ConfigurationException(
+                            "One-time authorization code feature is enabled, but no '%s' interface has been found"
+                                    .formatted(codeSenderInterfaceName),
+                            Set.of("quarkus.http.auth.form.otac.enabled"));
+                }
             }
-            return AdditionalBeanBuildItem.builder().setUnremovable().addBeanClass(FormAuthenticationMechanism.class)
-                    .setDefaultScope(SINGLETON).build();
         }
-        return null;
+    }
+
+    @BuildStep
+    List<AdditionalBeanBuildItem> registerFormAuthMechanismBeans(VertxHttpBuildTimeConfig httpBuildTimeConfig,
+            BuildProducer<UnremovableBeanBuildItem> unremovableBeanProducer) {
+        if (httpBuildTimeConfig.auth().form().enabled()) {
+            var formAuthMechanismBean = AdditionalBeanBuildItem.builder().setUnremovable()
+                    .addBeanClass(FormAuthenticationMechanism.class).setDefaultScope(SINGLETON).build();
+            if (httpBuildTimeConfig.auth().form().oneTimeAuthZCodeEnabled()) {
+                unremovableBeanProducer
+                        .produce(UnremovableBeanBuildItem.beanTypes(OneTimeAuthorizationCodeSender.class,
+                                OneTimeAuthorizationCodeAuthenticator.class));
+                var defaultOneTimePasswordAuthenticator = AdditionalBeanBuildItem
+                        .unremovableOf(InMemoryOneTimeAuthZCodeAuthenticator.class);
+                return List.of(formAuthMechanismBean, defaultOneTimePasswordAuthenticator);
+            }
+            return List.of(formAuthMechanismBean);
+        }
+        return List.of();
     }
 
     @BuildStep