fix(auth): re-add proxy-stripped /api prefix to browser-facing OAuth URLs (#1330)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: FelixTJDietrich

server/src/main/java/de/tum/cit/aet/hephaestus/core/auth/AuthProperties.java

@@ -15,6 +15,16 @@
  * integration tests override via {@code @TestPropertySource}.
  *
  * @param issuer          Canonical issuer URI; populates the {@code iss} claim.
+ * @param apiBasePath     Public path prefix the reverse proxy strips before requests reach this app
+ *                        (e.g. {@code /api} when Traefik strips {@code /api}); empty when the app is
+ *                        served at the origin root (local dev). Prepended when building the absolute,
+ *                        browser-reachable OAuth URLs — the authorization-request {@code redirect_uri}
+ *                        and the {@code /oauth2/authorization} init redirect — so the IdP and the
+ *                        callback land back on the proxied API path, not the SPA. It cannot be inferred
+ *                        from the request: prod runs {@code forward-headers-strategy: native} (Tomcat
+ *                        {@code RemoteIpValve}, kept for the pre-auth IP rate-limit trust model — see
+ *                        {@code ProxyTrustGuard}), which restores forwarded host/proto but NOT
+ *                        {@code X-Forwarded-Prefix}. Normalized to leading-slash / no-trailing-slash.
  * @param audience        Default {@code aud} claim for SPA cookies.
  * @param accessTtl       Cookie-JWT lifetime.
  * @param cookieName      Access-token cookie name (the {@code __Host-} prefix is
@@ -69,6 +79,7 @@
 @ConfigurationProperties(prefix = "hephaestus.auth")
 public record AuthProperties(
     @DefaultValue("http://localhost:8080") URI issuer,
+    @DefaultValue("") String apiBasePath,
     @DefaultValue("hephaestus-spa") String audience,
     @DefaultValue("15m") Duration accessTtl,
     @DefaultValue(DEFAULT_COOKIE_NAME) String cookieName,
@@ -86,6 +97,23 @@ public record AuthProperties(
      */
     public AuthProperties {
         loginProviders = loginProviders == null ? Map.of() : loginProviders;
+        apiBasePath = normalizeApiBasePath(apiBasePath);
+    }
+
+    /**
+     * Coerce {@code apiBasePath} to the leading-slash / no-trailing-slash form the OAuth-URL builders
+     * concatenate, so {@code api}, {@code /api} and {@code /api/} are equivalent and {@code /} or blank
+     * mean root — a misconfigured value can't silently produce {@code hostapi/…} or a double slash.
+     */
+    private static String normalizeApiBasePath(String value) {
+        if (value == null) {
+            return "";
+        }
+        String trimmed = value.trim().replaceAll("/+$", "");
+        if (trimmed.isEmpty()) {
+            return "";
+        }
+        return trimmed.startsWith("/") ? trimmed : "/" + trimmed;
     }
 
     /**

server/src/main/java/de/tum/cit/aet/hephaestus/core/auth/oauth/AuthBeginController.java

@@ -39,16 +39,21 @@ public class AuthBeginController {
     private final de.tum.cit.aet.hephaestus.core.auth.jwt.CookieBearerTokenResolver bearerTokenResolver;
     private final org.springframework.security.oauth2.jwt.JwtDecoder jwtDecoder;
 
+    /** Proxy-stripped API prefix re-added to the init redirect — see {@code AuthProperties#apiBasePath}. */
+    private final String apiBasePath;
+
     public AuthBeginController(
         ClientRegistrationRepository clientRegistrationRepository,
         AuthIntentCookie authIntentCookie,
         de.tum.cit.aet.hephaestus.core.auth.jwt.CookieBearerTokenResolver bearerTokenResolver,
-        de.tum.cit.aet.hephaestus.core.auth.jwt.RevocationAwareJwtDecoder jwtDecoder
+        de.tum.cit.aet.hephaestus.core.auth.jwt.RevocationAwareJwtDecoder jwtDecoder,
+        de.tum.cit.aet.hephaestus.core.auth.AuthProperties authProperties
     ) {
         this.clientRegistrationRepository = clientRegistrationRepository;
         this.authIntentCookie = authIntentCookie;
         this.bearerTokenResolver = bearerTokenResolver;
         this.jwtDecoder = jwtDecoder;
+        this.apiBasePath = authProperties.apiBasePath();
     }
 
     @GetMapping("/login")
@@ -89,8 +94,10 @@ public RedirectView begin(
         authIntentCookie.write(response, intent);
         // 302 to Spring's standard initiation endpoint; the OAuth2AuthorizationRequestRedirectFilter
         // takes over from here, building the upstream redirect with state + PKCE (see AuthSecurityConfig).
+        // apiBasePath re-adds the proxy-stripped prefix so the browser lands on the proxied init endpoint,
+        // not the SPA. (The /auth/error targets above are SPA routes at the origin root, so they keep none.)
         String urlEncodedRegistration = URLEncoder.encode(registrationId, StandardCharsets.UTF_8);
-        return new RedirectView(OAUTH_INIT_PATH + urlEncodedRegistration, false);
+        return new RedirectView(apiBasePath + OAUTH_INIT_PATH + urlEncodedRegistration, false);
     }
 
     /**

server/src/main/java/de/tum/cit/aet/hephaestus/core/auth/provider/LoginProviderClientRegistrationRepository.java

@@ -24,16 +24,26 @@ public class LoginProviderClientRegistrationRepository
     implements ClientRegistrationRepository, Iterable<ClientRegistration>, IdentityProviderCatalog
 {
 
-    private static final String CALLBACK_TEMPLATE = "{baseUrl}/login/oauth2/code/{registrationId}";
-
     private final LoginProviderRepository loginProviderRepository;
+
+    /**
+     * {@code redirect_uri} template. {@code {baseUrl}} expands per request to the public origin (scheme
+     * + host, restored by native forward-headers); {@code apiBasePath} re-adds the proxy-stripped prefix
+     * so the IdP redirects back to the proxied API path, not the SPA — see {@code AuthProperties#apiBasePath}.
+     */
+    private final String callbackTemplate;
+
     private final Cache<String, ClientRegistration> cache = Caffeine.newBuilder()
         .expireAfterWrite(Duration.ofSeconds(60))
         .maximumSize(256)
         .build();
 
-    public LoginProviderClientRegistrationRepository(LoginProviderRepository loginProviderRepository) {
+    public LoginProviderClientRegistrationRepository(
+        LoginProviderRepository loginProviderRepository,
+        String apiBasePath
+    ) {
         this.loginProviderRepository = loginProviderRepository;
+        this.callbackTemplate = "{baseUrl}" + apiBasePath + "/login/oauth2/code/{registrationId}";
     }
 
     @Override
@@ -79,7 +89,7 @@ private ClientRegistration toRegistration(LoginProvider provider) {
             .clientSecret(provider.getClientSecret())
             .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
             .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
-            .redirectUri(CALLBACK_TEMPLATE)
+            .redirectUri(callbackTemplate)
             .scope(provider.getScopes().trim().split("\\s+"))
             .userNameAttributeName("id")
             .clientName(provider.getDisplayName());

server/src/main/java/de/tum/cit/aet/hephaestus/core/auth/provider/LoginProviderConfiguration.java

@@ -1,5 +1,6 @@
 package de.tum.cit.aet.hephaestus.core.auth.provider;
 
+import de.tum.cit.aet.hephaestus.core.auth.AuthProperties;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
@@ -14,8 +15,9 @@ public class LoginProviderConfiguration {
 
     @Bean
     public LoginProviderClientRegistrationRepository loginProviderClientRegistrationRepository(
-        LoginProviderRepository loginProviderRepository
+        LoginProviderRepository loginProviderRepository,
+        AuthProperties authProperties
     ) {
-        return new LoginProviderClientRegistrationRepository(loginProviderRepository);
+        return new LoginProviderClientRegistrationRepository(loginProviderRepository, authProperties.apiBasePath());
     }
 }

server/src/main/java/de/tum/cit/aet/hephaestus/core/auth/web/LoginProviderAdminController.java

@@ -43,14 +43,30 @@ public class LoginProviderAdminController {
 
     private final LoginProviderService loginProviderService;
 
-    public LoginProviderAdminController(LoginProviderService loginProviderService) {
+    /** Proxy-stripped API prefix re-added to the displayed callback URL — see {@code AuthProperties#apiBasePath}. */
+    private final String apiBasePath;
+
+    public LoginProviderAdminController(
+        LoginProviderService loginProviderService,
+        de.tum.cit.aet.hephaestus.core.auth.AuthProperties authProperties
+    ) {
         this.loginProviderService = loginProviderService;
+        this.apiBasePath = authProperties.apiBasePath();
+    }
+
+    /**
+     * Public callback base the admin registers on the upstream OAuth app: the request origin (scheme +
+     * host, restored by native forward-headers) plus the proxy-stripped API prefix. The per-provider
+     * {@code /login/oauth2/code/{id}} segment is appended in {@link #toView}.
+     */
+    private String callbackBase() {
+        return ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString() + apiBasePath;
     }
 
     @GetMapping
     @Operation(summary = "List login providers", operationId = "adminListLoginProviders")
     public ResponseEntity<List<LoginProviderViewDTO>> list() {
-        String callbackBase = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
+        String callbackBase = callbackBase();
         return ResponseEntity.ok(
             loginProviderService
                 .listAll()
@@ -75,10 +91,7 @@ public ResponseEntity<LoginProviderViewDTO> create(@Valid @RequestBody CreateLog
                 body.scopes()
             )
         );
-        LoginProviderViewDTO view = toView(
-            created,
-            ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString()
-        );
+        LoginProviderViewDTO view = toView(created, callbackBase());
         URI location = ServletUriComponentsBuilder.fromCurrentRequest()
             .path("/{registrationId}")
             .buildAndExpand(created.getRegistrationId())
@@ -103,9 +116,7 @@ public ResponseEntity<LoginProviderViewDTO> update(
                 body.enabled()
             )
         );
-        return ResponseEntity.ok(
-            toView(updated, ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString())
-        );
+        return ResponseEntity.ok(toView(updated, callbackBase()));
     }
 
     @DeleteMapping("/{registrationId}")

server/src/main/resources/application-prod.yml

@@ -125,6 +125,9 @@ hephaestus:
     auth:
         issuer: ${HEPHAESTUS_AUTH_ISSUER}
         state-cookie-key: ${HEPHAESTUS_AUTH_STATE_COOKIE_KEY}
+        # Traefik strips /api before the request reaches the app (see docker/compose.app.yaml), and
+        # native forward-headers can't restore the prefix — re-add it to the browser-facing OAuth URLs.
+        api-base-path: /api
 
     # ═══════════════════════════════════════════════════════════════════════════
     # GITLAB INTEGRATION (Production)

server/src/test/java/de/tum/cit/aet/hephaestus/core/auth/AuthPropertiesFixture.java

@@ -0,0 +1,47 @@
+package de.tum.cit.aet.hephaestus.core.auth;
+
+import java.net.URI;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Shared {@link AuthProperties} builder for unit tests, so the 12-arg record construction lives in one
+ * place. Values are the production defaults; vary only the component under test.
+ */
+public final class AuthPropertiesFixture {
+
+    private AuthPropertiesFixture() {}
+
+    /** Production defaults (no proxy prefix, no seeded providers). */
+    public static AuthProperties defaults() {
+        return build("", Map.of());
+    }
+
+    /** Defaults with the given {@code apiBasePath} (the constructor normalizes it). */
+    public static AuthProperties withApiBasePath(String apiBasePath) {
+        return build(apiBasePath, Map.of());
+    }
+
+    /** Defaults with the given seeded login providers. */
+    public static AuthProperties withLoginProviders(Map<String, AuthProperties.LoginProviderSeed> loginProviders) {
+        return build("", loginProviders);
+    }
+
+    private static AuthProperties build(String apiBasePath, Map<String, AuthProperties.LoginProviderSeed> providers) {
+        return new AuthProperties(
+            URI.create("http://localhost:8080"),
+            apiBasePath,
+            "hephaestus-spa",
+            Duration.ofMinutes(15),
+            AuthProperties.DEFAULT_COOKIE_NAME,
+            "",
+            Duration.ofHours(48),
+            providers,
+            List.of(),
+            "",
+            Duration.ofHours(1),
+            Duration.ofHours(12)
+        );
+    }
+}

server/src/test/java/de/tum/cit/aet/hephaestus/core/auth/AuthPropertiesTest.java

@@ -0,0 +1,33 @@
+package de.tum.cit.aet.hephaestus.core.auth;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import de.tum.cit.aet.hephaestus.testconfig.BaseUnitTest;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+/**
+ * {@code apiBasePath} feeds string-concatenated OAuth URLs ({@code {baseUrl}} + path + callback), so a
+ * stray missing/duplicated slash silently breaks login. Pin the constructor normalization that makes
+ * {@code api}, {@code /api} and {@code /api/} equivalent and collapses blank/{@code /} to root.
+ */
+class AuthPropertiesTest extends BaseUnitTest {
+
+    @ParameterizedTest
+    @CsvSource(
+        value = {
+            "/api | /api",
+            "api | /api",
+            "/api/ | /api",
+            "/api/v2/ | /api/v2",
+            "'' | ''",
+            "/ | ''",
+            "'  /api/  ' | /api",
+        },
+        delimiterString = "|",
+        emptyValue = ""
+    )
+    void apiBasePath_isNormalizedToLeadingSlashNoTrailingSlash(String raw, String expected) {
+        assertThat(AuthPropertiesFixture.withApiBasePath(raw).apiBasePath()).isEqualTo(expected);
+    }
+}

server/src/test/java/de/tum/cit/aet/hephaestus/core/auth/jwt/CookieBearerTokenResolverTest.java

@@ -3,10 +3,9 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import de.tum.cit.aet.hephaestus.core.auth.AuthProperties;
+import de.tum.cit.aet.hephaestus.core.auth.AuthPropertiesFixture;
 import de.tum.cit.aet.hephaestus.testconfig.BaseUnitTest;
 import jakarta.servlet.http.Cookie;
-import java.net.URI;
-import java.time.Duration;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.springframework.mock.web.MockHttpServletRequest;
@@ -20,28 +19,15 @@
  */
 class CookieBearerTokenResolverTest extends BaseUnitTest {
 
-    private static final String COOKIE_NAME = "__Host-HEPHAESTUS_AT";
+    private static final String COOKIE_NAME = AuthProperties.DEFAULT_COOKIE_NAME;
     private static final String COOKIE_TOKEN = "cookie-token-trusted";
     private static final String HEADER_TOKEN = "attacker-token-hostile";
 
     private CookieBearerTokenResolver resolver;
 
     @BeforeEach
     void setUp() {
-        AuthProperties properties = new AuthProperties(
-            URI.create("http://localhost:8080"),
-            "hephaestus-spa",
-            Duration.ofMinutes(15),
-            COOKIE_NAME,
-            "",
-            Duration.ofHours(48),
-            java.util.Map.of(),
-            java.util.List.of(),
-            "",
-            Duration.ofHours(1),
-            Duration.ofHours(12)
-        );
-        resolver = new CookieBearerTokenResolver(properties);
+        resolver = new CookieBearerTokenResolver(AuthPropertiesFixture.defaults());
     }
 
     @Test

server/src/test/java/de/tum/cit/aet/hephaestus/core/auth/oauth/AuthBeginControllerLinkTest.java

@@ -6,6 +6,7 @@
 import static org.mockito.Mockito.verifyNoInteractions;
 import static org.mockito.Mockito.when;
 
+import de.tum.cit.aet.hephaestus.core.auth.AuthPropertiesFixture;
 import de.tum.cit.aet.hephaestus.core.auth.jwt.CookieBearerTokenResolver;
 import de.tum.cit.aet.hephaestus.core.auth.jwt.RevocationAwareJwtDecoder;
 import de.tum.cit.aet.hephaestus.testconfig.BaseUnitTest;
@@ -28,21 +29,32 @@
  */
 class AuthBeginControllerLinkTest extends BaseUnitTest {
 
+    private ClientRegistrationRepository registrations;
     private CookieBearerTokenResolver bearerTokenResolver;
     private RevocationAwareJwtDecoder jwtDecoder;
     private AuthIntentCookie authIntentCookie;
     private AuthBeginController controller;
 
     @BeforeEach
     void setUp() {
-        ClientRegistrationRepository registrations = mock(ClientRegistrationRepository.class);
+        registrations = mock(ClientRegistrationRepository.class);
         when(registrations.findByRegistrationId(any())).thenReturn(githubRegistration());
         bearerTokenResolver = mock(CookieBearerTokenResolver.class);
         jwtDecoder = mock(RevocationAwareJwtDecoder.class);
         byte[] key = new byte[32];
         new SecureRandom().nextBytes(key);
         authIntentCookie = new AuthIntentCookie(key);
-        controller = new AuthBeginController(registrations, authIntentCookie, bearerTokenResolver, jwtDecoder);
+        controller = buildController("");
+    }
+
+    private AuthBeginController buildController(String apiBasePath) {
+        return new AuthBeginController(
+            registrations,
+            authIntentCookie,
+            bearerTokenResolver,
+            jwtDecoder,
+            AuthPropertiesFixture.withApiBasePath(apiBasePath)
+        );
     }
 
     private static ClientRegistration githubRegistration() {
@@ -118,4 +130,18 @@ void loginMode_neverTouchesDecoder() {
         assertThat(intent.mode()).isEqualTo(AuthIntentCookie.Intent.Mode.LOGIN);
         verifyNoInteractions(jwtDecoder);
     }
+
+    @Test
+    void initRedirect_carriesApiBasePath_soItLandsOnTheProxiedEndpointNotTheSpa() {
+        RedirectView view = buildController("/api").begin(
+            "github",
+            "ws",
+            "/",
+            "login",
+            new MockHttpServletRequest(),
+            new MockHttpServletResponse()
+        );
+
+        assertThat(view.getUrl()).isEqualTo("/api/oauth2/authorization/github");
+    }
 }