feat: implement step 7 - frontend login/logout flow

Author: rhofkens

.env.example

@@ -0,0 +1,7 @@
+# Zitadel OIDC settings
+ZITADEL_AUTHDEMO_ISSUER_URI=https://issuer.zitadel.ch/oauth/v2
+ZITADEL_AUTHDEMO_CLIENT_ID=demo-frontend
+ZITADEL_AUTHDEMO_BACKEND_CLIENT_ID=demo-backend
+ZITADEL_AUTHDEMO_CLIENT_SECRET=change-me
+# Standard OIDC scopes
+ZITADEL_AUTHDEMO_SCOPES=openid profile email

.gitignore

@@ -27,3 +27,5 @@ Thumbs.db
 # Maven Wrapper - Ignore everything in .mvn except the wrapper jar
 .mvn/*
 !.mvn/wrapper/maven-wrapper.jar
+
+.env

CHANGELOG.md

@@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Step 01:** Initial repository scaffold, backend (Spring Boot) and frontend (React/Vite) skeletons, basic toolchain (Maven, pnpm, Vite, ESLint, Prettier, Spotless, Jacoco, Vitest), Husky pre-commit hooks, and GitHub Actions CI pipeline.
 - **Step 02:** Added public health endpoint.
 - **Step 03:** Guest UI skeleton with health fetch.
+- **Step 04:** Baseline error handling added.
+- **Step 05** – Implement client-side caching for public health endpoint using `sessionStorage` to display stale data when the backend is unavailable. Added a 'stale data' badge to the UI.
+- **Step 06** – Added OIDC configuration skeleton (using standard scopes), environment variable setup, and updated gitignore for `.env` files. Updated subsequent step plans (7, 8) to remove custom scope references.
+- **Step 07** – Implemented frontend login/logout flow using oidc-client-ts for PKCE. Added tests for Header, AuthCallback, AuthProvider, and AuthService.
 
 ### Fixed
 

README.md

@@ -40,6 +40,52 @@ The frontend development server will start on http://localhost:5173.
 
 > **Note:** The frontend dev server includes a proxy configuration that forwards all `/api` requests to the backend server running on port 8080. Make sure the backend server is running when developing the frontend.
 
+### Guest Mode Caching
+
+The frontend implements a caching mechanism for the public health check endpoint in guest mode.
+
+- The response from `/api/v1/public/health` is stored in the browser's `sessionStorage`.
+- If the backend is unavailable when the page loads, the UI will display the last known status from the cache ("stale data") instead of showing an error immediately.
+- During development, if you need to clear this cache to fetch fresh data, you can do so via your browser's developer tools (usually under the "Application" or "Storage" tab, look for `sessionStorage`).
+
+## Environment Variables
+
+This project uses environment variables for configuration, particularly for OIDC authentication details needed from Step 7 onwards. Template files are provided:
+
+- `.env.example` (at the project root, for backend configuration)
+- `frontend/.env.example` (in the frontend directory, for frontend configuration)
+
+These files list the required variables but contain placeholder values.
+
+**To configure your local environment:**
+
+1.  **Copy the templates:**
+    ```bash
+    cp .env.example .env
+    cp frontend/.env.example frontend/.env
+    ```
+2.  **Edit the `.env` files:** Open the newly created `.env` files (in the root directory and the `frontend/` directory) and replace the placeholder values with your actual Zitadel application details (Issuer URI, Client IDs, Client Secret). Refer to `docs/auth-config.md` for details on each variable.
+
+**Important:** The `.env` files contain sensitive information and are listed in `.gitignore`. **Never commit `.env` files to the Git repository.**
+
+
+## Running with OIDC
+
+The frontend application uses the OpenID Connect (OIDC) Authorization Code flow with Proof Key for Code Exchange (PKCE) for user authentication. This is implemented using the `oidc-client-ts` library.
+
+To run the application with OIDC authentication enabled, you need to configure the following environment variables in the `frontend/.env` file (refer to `frontend/.env.example` for the format):
+
+- `VITE_ZITADEL_ISSUER_URI`: The URI of your Zitadel instance.
+- `VITE_ZITADEL_CLIENT_ID`: The Client ID of your Zitadel application.
+- `VITE_ZITADEL_SCOPES`: The OIDC scopes required by the application (e.g., `openid profile email`).
+
+Additionally, ensure your Zitadel client application is configured with the following settings:
+
+- **Application Type:** `User Agent`
+- **Authentication Method:** `None` (PKCE is used)
+- **Redirect URIs:** `http://localhost:5173/auth/callback`
+- **Post Logout URIs:** `http://localhost:5173/`
+
 ## Testing
 
 ### Backend
@@ -113,4 +159,3 @@ Example response:
 {
   "message": "Service up"
 }
-```

backend/src/main/java/ai/bluefields/oidcauthdemo/error/ApiError.java

@@ -0,0 +1,34 @@
+package ai.bluefields.oidcauthdemo.error;
+
+import java.time.Instant;
+
+/**
+ * Represents a standardized error response following RFC 7807 "Problem Details for HTTP APIs". This
+ * record encapsulates error information to be returned to clients in a consistent format with the
+ * content type "application/problem+json".
+ *
+ * <p>The fields follow the RFC 7807 specification:
+ *
+ * <ul>
+ *   <li>{@code type} - A URI reference that identifies the problem type
+ *   <li>{@code title} - A short, human-readable summary of the problem type
+ *   <li>{@code status} - The HTTP status code for this occurrence of the problem
+ *   <li>{@code detail} - A human-readable explanation specific to this occurrence of the problem
+ *   <li>{@code timestamp} - The time when the error occurred (extension to the standard)
+ * </ul>
+ *
+ * <p>Example usage:
+ *
+ * <pre>
+ * ApiError error = new ApiError(
+ *     "https://api.bluefields.ai/errors/not-found",
+ *     "Resource Not Found",
+ *     404,
+ *     "The requested resource could not be found",
+ *     Instant.now()
+ * );
+ * </pre>
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc7807">RFC 7807</a>
+ */
+public record ApiError(String type, String title, int status, String detail, Instant timestamp) {}

backend/src/main/java/ai/bluefields/oidcauthdemo/error/GlobalExceptionHandler.java

@@ -0,0 +1,151 @@
+package ai.bluefields.oidcauthdemo.error;
+
+import java.time.Instant;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.HttpMediaTypeNotSupportedException;
+import org.springframework.web.HttpRequestMethodNotSupportedException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.servlet.NoHandlerFoundException;
+
+/**
+ * Global exception handler for the application that converts uncaught exceptions into standardized
+ * {@link ApiError} responses following RFC 7807 "Problem Details for HTTP APIs".
+ *
+ * <p>This class is responsible for:
+ *
+ * <ul>
+ *   <li>Catching exceptions thrown by controllers
+ *   <li>Converting them to standardized ApiError responses
+ *   <li>Setting the appropriate HTTP status code
+ *   <li>Setting the content type to "application/problem+json"
+ * </ul>
+ *
+ * <p>The handler prevents internal exception details from leaking to clients while still providing
+ * useful error information. All exceptions are logged for diagnostic purposes.
+ *
+ * <p>Example response:
+ *
+ * <pre>
+ * {
+ *   "type": "https://api.bluefields.ai/errors/internal-error",
+ *   "title": "Internal Server Error",
+ *   "status": 500,
+ *   "detail": "An unexpected error occurred while processing your request",
+ *   "timestamp": "2025-04-17T19:08:00Z"
+ * }
+ * </pre>
+ *
+ * @see ApiError
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc7807">RFC 7807</a>
+ */
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+  private static final Logger logger = LoggerFactory.getLogger(GlobalExceptionHandler.class);
+
+  /**
+   * Handles all uncaught exceptions and converts them to a standardized {@link ApiError} response
+   * with HTTP status 500 (Internal Server Error).
+   *
+   * <p>This method logs the exception for diagnostic purposes but returns a generic error message
+   * to the client to avoid exposing sensitive implementation details.
+   *
+   * @param ex the exception that was thrown
+   * @return a {@link ResponseEntity} containing an {@link ApiError} with status 500
+   */
+  @ExceptionHandler(Exception.class)
+  public ResponseEntity<ApiError> handleException(Exception ex) {
+    logger.error("Unhandled exception caught by global handler", ex);
+
+    ApiError apiError =
+        new ApiError(
+            "https://api.bluefields.ai/errors/internal-error",
+            "Internal Server Error",
+            HttpStatus.INTERNAL_SERVER_ERROR.value(),
+            "An unexpected error occurred while processing your request",
+            Instant.now());
+
+    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .contentType(MediaType.valueOf("application/problem+json"))
+        .body(apiError);
+  }
+
+  /**
+   * Handles {@link NoHandlerFoundException} and converts it to a standardized {@link ApiError}
+   * response with HTTP status 404 (Not Found).
+   *
+   * @param ex the exception that was thrown
+   * @return a {@link ResponseEntity} containing an {@link ApiError} with status 404
+   */
+  @ExceptionHandler(NoHandlerFoundException.class)
+  public ResponseEntity<ApiError> handleNoHandlerFoundException(NoHandlerFoundException ex) {
+    logger.warn("No handler found for {}: {}", ex.getRequestURL(), ex.getMessage());
+
+    ApiError apiError =
+        new ApiError(
+            "https://api.bluefields.ai/errors/not-found",
+            "Not Found",
+            HttpStatus.NOT_FOUND.value(),
+            "The requested resource could not be found: " + ex.getRequestURL(),
+            Instant.now());
+
+    return ResponseEntity.status(HttpStatus.NOT_FOUND)
+        .contentType(MediaType.valueOf("application/problem+json"))
+        .body(apiError);
+  }
+
+  /**
+   * Handles {@link HttpRequestMethodNotSupportedException} and converts it to a standardized {@link
+   * ApiError} response with HTTP status 405 (Method Not Allowed).
+   *
+   * @param ex the exception that was thrown
+   * @return a {@link ResponseEntity} containing an {@link ApiError} with status 405
+   */
+  @ExceptionHandler(HttpRequestMethodNotSupportedException.class)
+  public ResponseEntity<ApiError> handleMethodNotAllowed(
+      HttpRequestMethodNotSupportedException ex) {
+    logger.warn("Method not allowed: {}", ex.getMessage());
+
+    ApiError apiError =
+        new ApiError(
+            "https://api.bluefields.ai/errors/method-not-allowed",
+            "Method Not Allowed",
+            HttpStatus.METHOD_NOT_ALLOWED.value(),
+            "The HTTP method " + ex.getMethod() + " is not supported for this resource",
+            Instant.now());
+
+    return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED)
+        .contentType(MediaType.valueOf("application/problem+json"))
+        .body(apiError);
+  }
+
+  /**
+   * Handles {@link HttpMediaTypeNotSupportedException} and converts it to a standardized {@link
+   * ApiError} response with HTTP status 415 (Unsupported Media Type).
+   *
+   * @param ex the exception that was thrown
+   * @return a {@link ResponseEntity} containing an {@link ApiError} with status 415
+   */
+  @ExceptionHandler(HttpMediaTypeNotSupportedException.class)
+  public ResponseEntity<ApiError> handleUnsupportedMediaType(
+      HttpMediaTypeNotSupportedException ex) {
+    logger.warn("Unsupported media type: {}", ex.getMessage());
+
+    ApiError apiError =
+        new ApiError(
+            "https://api.bluefields.ai/errors/unsupported-media-type",
+            "Unsupported Media Type",
+            HttpStatus.UNSUPPORTED_MEDIA_TYPE.value(),
+            "The content type " + ex.getContentType() + " is not supported",
+            Instant.now());
+
+    return ResponseEntity.status(HttpStatus.UNSUPPORTED_MEDIA_TYPE)
+        .contentType(MediaType.valueOf("application/problem+json"))
+        .body(apiError);
+  }
+}

backend/src/main/resources/application.properties

@@ -1 +1,5 @@
 spring.application.name=oidc-auth-demo
+
+# Enable throwing NoHandlerFoundException for 404 errors
+spring.mvc.throw-exception-if-no-handler-found=true
+spring.web.resources.add-mappings=false

backend/src/main/resources/application.yaml

@@ -0,0 +1,14 @@
+spring:
+  security:
+    # NOTE: Security is currently disabled. It will be enabled in Step 08.
+    enabled: false
+    oauth2:
+      resourceserver:
+        jwt:
+          # Use environment variable ZITADEL_AUTHDEMO_ISSUER_URI, default to empty string if not set
+          issuer-uri: ${ZITADEL_AUTHDEMO_ISSUER_URI:}
+zitadel:
+  # Use environment variable ZITADEL_AUTHDEMO_BACKEND_CLIENT_ID, default to empty string if not set
+  client-id: ${ZITADEL_AUTHDEMO_BACKEND_CLIENT_ID:}
+  # Use environment variable ZITADEL_AUTHDEMO_CLIENT_SECRET, default to empty string if not set
+  client-secret: ${ZITADEL_AUTHDEMO_CLIENT_SECRET:}

backend/src/test/java/ai/bluefields/oidcauthdemo/error/ApiErrorTest.java

@@ -0,0 +1,62 @@
+package ai.bluefields.oidcauthdemo.error;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.time.Instant;
+import org.junit.jupiter.api.Test;
+
+/** Unit tests for {@link ApiError} record. */
+class ApiErrorTest {
+
+  @Test
+  void shouldCreateApiErrorWithAllFields() {
+    // Given
+    String type = "https://api.bluefields.ai/errors/validation";
+    String title = "Validation Error";
+    int status = 400;
+    String detail = "The request was invalid";
+    Instant timestamp = Instant.now();
+
+    // When
+    ApiError apiError = new ApiError(type, title, status, detail, timestamp);
+
+    // Then
+    assertThat(apiError.type()).isEqualTo(type);
+    assertThat(apiError.title()).isEqualTo(title);
+    assertThat(apiError.status()).isEqualTo(status);
+    assertThat(apiError.detail()).isEqualTo(detail);
+    assertThat(apiError.timestamp()).isEqualTo(timestamp);
+  }
+
+  @Test
+  void shouldHaveCorrectEqualsAndHashCode() {
+    // Given
+    Instant now = Instant.now();
+    ApiError error1 = new ApiError("type", "title", 400, "detail", now);
+    ApiError error2 = new ApiError("type", "title", 400, "detail", now);
+    ApiError differentError = new ApiError("different", "title", 400, "detail", now);
+
+    // Then
+    assertThat(error1).isEqualTo(error2);
+    assertThat(error1.hashCode()).isEqualTo(error2.hashCode());
+    assertThat(error1).isNotEqualTo(differentError);
+    assertThat(error1.hashCode()).isNotEqualTo(differentError.hashCode());
+  }
+
+  @Test
+  void shouldHaveCorrectToString() {
+    // Given
+    Instant now = Instant.now();
+    ApiError error = new ApiError("type", "title", 400, "detail", now);
+
+    // When
+    String toString = error.toString();
+
+    // Then
+    assertThat(toString).contains("type");
+    assertThat(toString).contains("title");
+    assertThat(toString).contains("400");
+    assertThat(toString).contains("detail");
+    assertThat(toString).contains(now.toString());
+  }
+}