FINERACT-2641: Implement Authentication Feature

.github/workflows/build-tests-backend.yml

@@ -65,6 +65,9 @@ jobs:
         with:
           validate-wrappers: true
 
+      - name: Generate dev JWT signing key
+        run: ./scripts/generate-dev-jwt-key.sh
+
       - name: Start application stack
         run: docker compose up -d --build --wait --wait-timeout 180
 

.github/workflows/build-tests-frontend.yml

@@ -103,6 +103,10 @@ jobs:
         if: steps.pw-cache.outputs.cache-hit == 'true'
         run: npx playwright install-deps chromium
 
+      - name: Generate dev JWT signing key
+        working-directory: ${{ github.workspace }}
+        run: ./consumer/scripts/generate-dev-jwt-key.sh
+
       - name: Bring up e2e stack
         working-directory: ${{ github.workspace }}
         run: docker compose -f docker-compose.e2e.yml up -d --build --wait --wait-timeout 360

consumer/.gitignore

@@ -52,3 +52,6 @@ out/
 
 ### VS Code ###
 .vscode/
+
+### Local secrets — never commit ###
+dev-jwt-key.pem

consumer/build.gradle

@@ -91,7 +91,7 @@ tasks.named('test') {
 
 cucumber {
 	featurePath = 'src/test/resources/features'
-	glue = 'org.apache.fineract.consumer.cucumber.steps'
+	glue = 'org.apache.fineract.consumer.cucumber'
 	plugin = ['pretty']
 }
 

consumer/compose.yaml

@@ -100,7 +100,10 @@ services:
       FINERACT_BASE_URL: http://fineract:8080/fineract-provider/api/v1
       SPRING_MAIL_HOST: mailpit
       SERVER_FORWARD_HEADERS_STRATEGY: framework
+      JWT_KEY_LOCATION: file:/etc/bff/jwt-key.pem
       JAVA_TOOL_OPTIONS: "-Xmx768m -Xms256m"
+    volumes:
+      - ./dev-jwt-key.pem:/etc/bff/jwt-key.pem:ro
     ports:
       - "8080:8080"
     healthcheck:

consumer/scripts/generate-dev-jwt-key.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Generates the dev/CI JWT signing keypair (EC P-256, for ES256) as a PEM file.
+# Dev-only convenience — prod injects the PEM from a secret manager instead.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+KEY_FILE="dev-jwt-key.pem"
+
+if [ -f "$KEY_FILE" ]; then
+  echo "Dev JWT key already exists at consumer/$KEY_FILE — leaving it untouched."
+  exit 0
+fi
+
+umask 077
+
+openssl ecparam -name prime256v1 -genkey -noout \
+  | openssl pkcs8 -topk8 -nocrypt -out "$KEY_FILE"
+openssl ec -in "$KEY_FILE" -pubout >> "$KEY_FILE" 2>/dev/null
+
+echo "Generated dev JWT signing key at consumer/$KEY_FILE"

consumer/src/main/java/org/apache/fineract/consumer/authentication/command/api/AuthenticationCommandController.java

@@ -0,0 +1,134 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fineract.consumer.authentication.command.api;
+
+import jakarta.validation.Valid;
+import java.time.Duration;
+import java.time.Instant;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.consumer.authentication.command.data.AuthenticationConstants;
+import org.apache.fineract.consumer.authentication.command.data.EstablishedSessionCommandData;
+import org.apache.fineract.consumer.authentication.command.data.LoginChallengeCommandData;
+import org.apache.fineract.consumer.authentication.command.data.LoginCommand;
+import org.apache.fineract.consumer.authentication.command.data.LoginCommandRequest;
+import org.apache.fineract.consumer.authentication.command.data.LogoutCommand;
+import org.apache.fineract.consumer.authentication.command.data.RefreshSessionCommand;
+import org.apache.fineract.consumer.authentication.command.data.SessionCommandData;
+import org.apache.fineract.consumer.authentication.command.data.VerifyTwoFactorCommand;
+import org.apache.fineract.consumer.authentication.command.data.VerifyTwoFactorCommandRequest;
+import org.apache.fineract.consumer.authentication.command.exception.RefreshTokenInvalidException;
+import org.apache.fineract.consumer.authentication.command.service.AuthenticationCommandService;
+import org.apache.fineract.consumer.infrastructure.configs.AuthenticationProperties;
+import org.apache.fineract.consumer.infrastructure.web.ConsumerHeaders;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.ResponseCookie;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.CookieValue;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/v1/authentication")
+@RequiredArgsConstructor
+public class AuthenticationCommandController {
+
+    private static final String REFRESH_COOKIE_PATH = "/api/v1/authentication";
+    private static final String SAME_SITE_STRICT = "Strict";
+
+    private final AuthenticationCommandService authenticationCommandService;
+    private final AuthenticationProperties authenticationProperties;
+
+    @PostMapping("/login")
+    public ResponseEntity<LoginChallengeCommandData> login(
+            @Valid @RequestBody LoginCommandRequest request,
+            @RequestHeader(ConsumerHeaders.DEVICE_FINGERPRINT) String deviceFingerprint) {
+        LoginCommand command = LoginCommand.builder()
+                .email(request.getEmail())
+                .password(request.getPassword())
+                .deviceFingerprint(deviceFingerprint)
+                .build();
+        return ResponseEntity.ok(authenticationCommandService.login(command));
+    }
+
+    @PostMapping("/2fa")
+    public ResponseEntity<SessionCommandData> verifyTwoFactor(
+            @Valid @RequestBody VerifyTwoFactorCommandRequest request,
+            @RequestHeader(ConsumerHeaders.DEVICE_FINGERPRINT) String deviceFingerprint) {
+        VerifyTwoFactorCommand command = VerifyTwoFactorCommand.builder()
+                .challengeToken(request.getChallengeToken())
+                .token(request.getToken())
+                .deviceFingerprint(deviceFingerprint)
+                .build();
+        return sessionResponse(authenticationCommandService.verifyTwoFactor(command));
+    }
+
+    @PostMapping("/refresh")
+    public ResponseEntity<SessionCommandData> refresh(
+            @CookieValue(value = AuthenticationConstants.REFRESH_TOKEN_COOKIE_NAME, required = false) String refreshToken,
+            @RequestHeader(ConsumerHeaders.DEVICE_FINGERPRINT) String deviceFingerprint) {
+        if (refreshToken == null) {
+            throw new RefreshTokenInvalidException();
+        }
+        RefreshSessionCommand command = RefreshSessionCommand.builder()
+                .refreshToken(refreshToken)
+                .deviceFingerprint(deviceFingerprint)
+                .build();
+        return sessionResponse(authenticationCommandService.refresh(command));
+    }
+
+    @PostMapping("/logout")
+    public ResponseEntity<Void> logout(
+            @CookieValue(value = AuthenticationConstants.REFRESH_TOKEN_COOKIE_NAME, required = false) String refreshToken) {
+        if (refreshToken != null) {
+            authenticationCommandService.logout(LogoutCommand.builder()
+                    .refreshToken(refreshToken)
+                    .build());
+        }
+        return ResponseEntity.noContent()
+                .header(HttpHeaders.SET_COOKIE, refreshCookie("", Duration.ZERO).toString())
+                .build();
+    }
+
+    private ResponseEntity<SessionCommandData> sessionResponse(EstablishedSessionCommandData session) {
+        ResponseCookie cookie = refreshCookie(
+                session.getRefreshToken(),
+                Duration.between(Instant.now(), session.getRefreshTokenExpiresAt()));
+        SessionCommandData body = SessionCommandData.builder()
+                .accessToken(session.getAccessToken())
+                .expiresAt(session.getAccessTokenExpiresAt())
+                .build();
+        return ResponseEntity.ok()
+                .header(HttpHeaders.SET_COOKIE, cookie.toString())
+                .body(body);
+    }
+
+    private ResponseCookie refreshCookie(String value, Duration maxAge) {
+        return ResponseCookie.from(AuthenticationConstants.REFRESH_TOKEN_COOKIE_NAME, value)
+                .httpOnly(true)
+                .secure(authenticationProperties.isRefreshCookieSecure())
+                .sameSite(SAME_SITE_STRICT)
+                .path(REFRESH_COOKIE_PATH)
+                .maxAge(maxAge)
+                .build();
+    }
+}

consumer/src/main/java/org/apache/fineract/consumer/authentication/command/data/AuthenticationConstants.java

@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fineract.consumer.authentication.command.data;
+
+public final class AuthenticationConstants {
+
+    private AuthenticationConstants() {
+    }
+
+    public static final String REFRESH_TOKEN_COOKIE_NAME = "refresh_token";
+    public static final String CHALLENGE_PURPOSE_VALUE = "2fa_challenge";
+    public static final String BEARER_TOKEN_TYPE = "Bearer";
+}

consumer/src/main/java/org/apache/fineract/consumer/authentication/command/data/EstablishedSessionCommandData.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fineract.consumer.authentication.command.data;
+
+import java.time.Instant;
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.ToString;
+
+@Getter
+@RequiredArgsConstructor
+@Builder
+@EqualsAndHashCode
+@ToString(onlyExplicitlyIncluded = true)
+public final class EstablishedSessionCommandData {
+
+    private final String accessToken;
+    @ToString.Include
+    private final Instant accessTokenExpiresAt;
+    private final String refreshToken;
+    @ToString.Include
+    private final Instant refreshTokenExpiresAt;
+}

consumer/src/main/java/org/apache/fineract/consumer/authentication/command/data/LoginChallengeCommandData.java

@@ -0,0 +1,41 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fineract.consumer.authentication.command.data;
+
+import java.time.Instant;
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.ToString;
+
+@Getter
+@RequiredArgsConstructor
+@Builder
+@EqualsAndHashCode
+@ToString(onlyExplicitlyIncluded = true)
+public final class LoginChallengeCommandData {
+
+    private final String challengeToken;
+    @ToString.Include
+    private final Instant expiresAt;
+    @ToString.Include
+    private final String sentTo;
+}

consumer/src/main/java/org/apache/fineract/consumer/authentication/command/data/LoginCommand.java

@@ -0,0 +1,36 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fineract.consumer.authentication.command.data;
+
+import lombok.Builder;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.ToString;
+
+@Getter
+@RequiredArgsConstructor
+@Builder
+@ToString(onlyExplicitlyIncluded = true)
+public final class LoginCommand {
+
+    private final String email;
+    private final String password;
+    private final String deviceFingerprint;
+}