initial commit

2025-11-28 12:33:37 -03:00
commit 5da54393ff
42 changed files with 3251 additions and 0 deletions
--- a/.env.example
+++ b/.env.example
@@ -0,0 +1,40 @@
+# ===========================================
+# Environment Configuration
+# ===========================================
+# Copy this file to .env and fill in the values
+
+# -------------------------------------------
+# Keycloak Configuration
+# -------------------------------------------
+# Internal URL for backend-to-Keycloak communication (inside Docker network)
+KEYCLOAK_SERVER_URL=http://keycloak:8080/
+# External URL for browser redirects (accessible from host machine)
+KEYCLOAK_EXTERNAL_URL=http://localhost:8081/
+KEYCLOAK_REALM=your-realm
+KEYCLOAK_CLIENT_ID=your-client-id
+KEYCLOAK_CLIENT_SECRET=your-client-secret
+
+# -------------------------------------------
+# Frontend Configuration
+# -------------------------------------------
+# URL where the React frontend is running
+FRONTEND_URL=http://localhost:3000
+
+# -------------------------------------------
+# Cookie Configuration
+# -------------------------------------------
+# Name of the authentication cookie
+COOKIE_NAME=access_token
+
+# Set to true in production with HTTPS
+COOKIE_SECURE=false
+
+# Cookie SameSite policy: "lax", "strict", or "none"
+# Use "lax" for most cases, "none" for cross-site (requires COOKIE_SECURE=true)
+COOKIE_SAMESITE=lax
+
+# Cookie domain (leave empty for current domain, or set to .yourdomain.com for subdomains)
+COOKIE_DOMAIN=
+
+# Cookie max age in seconds (default: 3600 = 1 hour)
+COOKIE_MAX_AGE=3600
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,48 @@
+# Environment files
+.env
+*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+venv/
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+frontend/dist/
+*.tsbuildinfo
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
--- a/README.md
+++ b/README.md
@@ -0,0 +1,243 @@
+# FastAPI Keycloak Integration with React Frontend
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Project Structure](#project-structure)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Authentication Flow](#authentication-flow)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Introduction
+
+This project provides a full-stack authentication solution using FastAPI as the backend, React (with TypeScript and Tailwind CSS) as the frontend, and Keycloak as the identity provider. Authentication is handled securely using HTTP-only cookies to protect tokens from XSS attacks.
+
+## Features
+
+- **FastAPI Backend**: A modern, fast web framework for building APIs with Python 3.12+
+- **React Frontend**: TypeScript-based React application with Tailwind CSS for styling
+- **Keycloak Integration**: Enterprise-grade identity management with OAuth2/OpenID Connect
+- **Secure Cookie-Based Auth**: HTTP-only cookies protect access tokens from XSS attacks
+- **Dockerized Setup**: Full Docker Compose setup including Keycloak, backend, and frontend
+- **Poetry for Python Dependencies**: Simplified Python dependency management
+
+## Project Structure
+
+```
+.
+├── .env.example              # Environment variables template
+├── docker-compose.yaml       # Production Docker Compose
+├── docker-compose.dev.yaml   # Development Docker Compose
+├── README.md
+├── backend/
+│   ├── Dockerfile
+│   ├── pyproject.toml
+│   ├── poetry.lock
+│   └── src/
+│       ├── __init__.py
+│       ├── config.py         # Keycloak & cookie settings
+│       ├── controller.py     # Request handlers
+│       ├── main.py           # FastAPI app with CORS
+│       ├── models.py         # Pydantic models
+│       └── service.py        # Keycloak auth service
+└── frontend/
+    ├── Dockerfile
+    ├── nginx.conf            # Production nginx config
+    ├── package.json
+    ├── tsconfig.json
+    ├── tailwind.config.js
+    ├── vite.config.ts
+    └── src/
+        ├── App.tsx
+        ├── main.tsx
+        ├── index.css
+        ├── components/       # Reusable UI components
+        ├── context/          # React Context (AuthContext)
+        ├── hooks/            # Custom hooks (useAuth)
+        ├── pages/            # Page components
+        ├── services/         # API service layer
+        └── types/            # TypeScript types
+```
+
+## Prerequisites
+
+- [Docker](https://www.docker.com/get-started) and [Docker Compose](https://docs.docker.com/compose/install/)
+- [Node.js 20+](https://nodejs.org/) (for local frontend development)
+- [Python 3.12+](https://www.python.org/downloads/) (for local backend development)
+- [Git](https://git-scm.com/)
+
+## Installation
+
+1. **Clone the Repository**
+
+   ```bash
+   git clone https://github.com/your-repo/fastapi-keycloak.git
+   cd fastapi-keycloak
+   ```
+
+2. **Copy Environment Variables File**
+
+   ```bash
+   cp .env.example .env
+   ```
+
+3. **Configure Environment Variables**
+
+   Open the `.env` file and update the following variables:
+
+   ```env
+   # Keycloak Configuration
+   KEYCLOAK_SERVER_URL=http://localhost:8081/
+   KEYCLOAK_REALM=your-realm
+   KEYCLOAK_CLIENT_ID=your-client-id
+   KEYCLOAK_CLIENT_SECRET=your-client-secret
+
+   # Frontend URL (for CORS and redirects)
+   FRONTEND_URL=http://localhost:3000
+
+   # Cookie Configuration
+   COOKIE_SECURE=false    # Set to true in production with HTTPS
+   COOKIE_SAMESITE=lax
+   COOKIE_MAX_AGE=3600
+   ```
+
+## Configuration
+
+### Setting Up Keycloak
+
+1. **Start the Services**
+
+   ```bash
+   docker-compose up keycloak -d
+   ```
+
+2. **Access the Keycloak Admin Console**
+
+   Open `http://localhost:8081/` and login with:
+   - Username: `admin`
+   - Password: `admin`
+
+3. **Create a New Realm**
+
+   - Click "Create Realm"
+   - Name it (e.g., `my-app`)
+   - Click "Create"
+
+4. **Create a New Client**
+
+   - Go to Clients → Create client
+   - Client ID: e.g., `my-app-client`
+   - Client Protocol: `openid-connect`
+   - Click Next
+   - Enable "Client authentication" (confidential)
+   - Enable "Standard flow" and "Direct access grants"
+   - Click Next
+   - Valid redirect URIs: `http://localhost:8080/*`
+   - Web origins: `http://localhost:3000`
+   - Click Save
+
+5. **Get Client Secret**
+
+   - Go to Credentials tab
+   - Copy the "Client secret"
+   - Update your `.env` file
+
+6. **Create a Test User**
+
+   - Go to Users → Add user
+   - Username: `testuser`
+   - Email: `test@example.com`
+   - Click Create
+   - Go to Credentials tab → Set password
+   - Disable "Temporary"
+
+## Usage
+
+### Running with Docker (Production)
+
+```bash
+# Start all services
+docker-compose up --build
+
+# Services will be available at:
+# - Frontend: http://localhost:3000
+# - Backend API: http://localhost:8080
+# - Keycloak: http://localhost:8081
+```
+
+### Running with Docker (Development)
+
+For development with hot-reload on the backend:
+
+```bash
+# Start Keycloak and Backend only
+docker-compose -f docker-compose.dev.yaml up --build
+
+# In another terminal, start the frontend dev server
+cd frontend
+npm install
+npm run dev
+```
+
+## Authentication Flow
+
+1. **User clicks "Login"** → Frontend redirects to `/api/login`
+2. **Backend redirects to Keycloak** → User authenticates with Keycloak
+3. **Keycloak redirects back** → Backend receives authorization code at `/api/callback`
+4. **Backend exchanges code for token** → Sets HTTP-only cookie with access token
+5. **Backend redirects to frontend** → User lands on `/dashboard`
+6. **Frontend calls `/api/auth/me`** → Backend validates cookie and returns user info
+
+### API Endpoints
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/api` | GET | No | Welcome message and docs link |
+| `/api/login` | GET | No | Initiates OAuth2 login flow |
+| `/api/callback` | GET | No | OAuth2 callback (sets cookie) |
+| `/api/auth/me` | GET | Cookie | Get current user info |
+| `/api/auth/logout` | POST | Cookie | Clear auth cookie |
+| `/api/protected` | GET | Bearer | Protected endpoint (token in header) |
+| `/docs` | GET | No | Swagger API documentation |
+
+## Development
+
+### Backend Development
+
+```bash
+cd backend
+poetry install
+poetry run uvicorn src.main:app --reload --port 8080
+```
+
+### Frontend Development
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+The frontend dev server runs on `http://localhost:3000` and proxies `/api` requests to the backend.
+
+### Environment Variables
+
+See `.env.example` for all available configuration options:
+
+- **Keycloak settings**: Server URL, realm, client ID/secret
+- **Frontend URL**: For CORS and OAuth redirects
+- **Cookie settings**: Security options for the auth cookie
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue.
+
+## License
+
+This project is licensed under the MIT License.
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -0,0 +1,26 @@
+FROM python:3.12-slim
+
+ENV POETRY_VERSION=1.6.1 \
+    POETRY_NO_INTERACTION=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+RUN apt-get update \
+    && apt-get install -y curl build-essential \
+    && apt-get clean
+
+RUN curl -sSL https://install.python-poetry.org | python3 -
+
+ENV PATH="/root/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY pyproject.toml ./
+
+RUN poetry lock --no-update && poetry install --no-root
+
+COPY . .
+
+EXPOSE 8080
+
+CMD ["poetry", "run", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080", "--reload"]
--- a/backend/poetry.lock
+++ b/backend/poetry.lock
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -0,0 +1,18 @@
+[tool.poetry]
+name = "periodic-table"
+version = "0.1.0"
+description = "FastAPI Keycloak Authentication"
+authors = ["OntoKG"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+python-keycloak = "^5.8.1"
+fastapi = "^0.115.0"
+pydantic = "^2.12.4"
+pydantic-settings = "^2.12.0"
+uvicorn = {extras = ["standard"], version = "^0.32.0"}
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
--- a/backend/src/init.py
+++ b/backend/src/init.py
--- a/backend/src/config.py
+++ b/backend/src/config.py
@@ -0,0 +1,49 @@
+from pydantic_settings import BaseSettings
+from pydantic import Field
+from keycloak import KeycloakOpenID
+
+
+class Settings(BaseSettings):
+    # Keycloak settings
+    keycloak_server_url: str = Field(..., env="KEYCLOAK_SERVER_URL")
+    keycloak_external_url: str = Field(..., env="KEYCLOAK_EXTERNAL_URL")
+    keycloak_realm: str = Field(..., env="KEYCLOAK_REALM")
+    keycloak_client_id: str = Field(..., env="KEYCLOAK_CLIENT_ID")
+    keycloak_client_secret: str = Field(..., env="KEYCLOAK_CLIENT_SECRET")
+
+    # Frontend settings
+    frontend_url: str = Field(default="http://localhost:3000", env="FRONTEND_URL")
+
+    # Cookie settings
+    cookie_secure: bool = Field(default=False, env="COOKIE_SECURE")
+    cookie_samesite: str = Field(default="lax", env="COOKIE_SAMESITE")
+    cookie_domain: str | None = Field(default=None, env="COOKIE_DOMAIN")
+    cookie_max_age: int = Field(default=3600, env="COOKIE_MAX_AGE")
+    cookie_name: str = Field(default="access_token", env="COOKIE_NAME")
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+
+
+settings = Settings()
+
+keycloak_openid = KeycloakOpenID(
+    server_url=settings.keycloak_server_url,
+    realm_name=settings.keycloak_realm,
+    client_id=settings.keycloak_client_id,
+    client_secret_key=settings.keycloak_client_secret,
+    verify=False
+)
+
+
+def get_openid_config():
+    return keycloak_openid.well_known()
+
+
+def get_openid():
+    return keycloak_openid
+
+
+def get_settings():
+    return settings
--- a/backend/src/controller.py
+++ b/backend/src/controller.py
@@ -0,0 +1,169 @@
+from fastapi import Depends, HTTPException, status, Request
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from fastapi.responses import RedirectResponse, JSONResponse
+from src.models import TokenResponse, UserInfo
+from src.service import AuthService
+from src.config import get_settings
+
+# Initialize HTTPBearer security dependency
+bearer_scheme = HTTPBearer()
+
+# Get settings
+settings = get_settings()
+
+
+class AuthController:
+    """
+    Controller for handling authentication logic.
+    """
+
+    @staticmethod
+    def read_root():
+        """
+        Root endpoint providing basic information and documentation link.
+
+        Returns:
+            dict: A welcome message and link to the documentation.
+        """
+        return {
+            "message": (
+                "Welcome to the Keycloak authentication system. "
+                "Use the /api/login endpoint to authenticate and /api/auth/me "
+                "endpoint to access the authenticated user information."
+            ),
+            "documentation": "/docs",
+        }
+
+    @staticmethod
+    def login(keycode: str, request: Request) -> RedirectResponse:
+        """
+        Authenticate user, set HTTP-only cookie, and redirect to frontend.
+
+        Args:
+            keycode (str): The authorization code from Keycloak.
+            request (Request): The FastAPI request object.
+
+        Raises:
+            HTTPException: If the authentication fails.
+
+        Returns:
+            RedirectResponse: Redirects to frontend with cookie set.
+        """
+        # Authenticate the user using the AuthService
+        access_token = AuthService.authenticate_user(keycode, request)
+
+        if not access_token:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authentication failed",
+            )
+
+        # Create redirect response to frontend
+        response = RedirectResponse(
+            url=f"{settings.frontend_url}/dashboard",
+            status_code=status.HTTP_302_FOUND
+        )
+
+        # Set HTTP-only cookie with the access token
+        response.set_cookie(
+            key=settings.cookie_name,
+            value=access_token,
+            httponly=True,
+            secure=settings.cookie_secure,
+            samesite=settings.cookie_samesite,
+            max_age=settings.cookie_max_age,
+            domain=settings.cookie_domain,
+            path="/",
+        )
+
+        return response
+
+    @staticmethod
+    def get_current_user(request: Request) -> UserInfo:
+        """
+        Get the current authenticated user from the session cookie.
+
+        Args:
+            request (Request): The FastAPI request object.
+
+        Raises:
+            HTTPException: If no valid session cookie exists.
+
+        Returns:
+            UserInfo: Information about the authenticated user.
+        """
+        # Extract the token from the cookie
+        token = request.cookies.get(settings.cookie_name)
+
+        if not token:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Not authenticated",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        # Verify the token and get user information
+        user_info = AuthService.verify_token(token)
+
+        if not user_info:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid or expired session",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        return user_info
+
+    @staticmethod
+    def logout() -> JSONResponse:
+        """
+        Logout the user by clearing the authentication cookie.
+
+        Returns:
+            JSONResponse: Success message with cookie cleared.
+        """
+        response = JSONResponse(
+            content={"message": "Successfully logged out"},
+            status_code=status.HTTP_200_OK
+        )
+
+        # Clear the authentication cookie
+        response.delete_cookie(
+            key=settings.cookie_name,
+            path="/",
+            domain=settings.cookie_domain,
+        )
+
+        return response
+
+    @staticmethod
+    def protected_endpoint(
+        credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+    ) -> UserInfo:
+        """
+        Access a protected resource that requires valid token authentication.
+
+        Args:
+            credentials (HTTPAuthorizationCredentials): Bearer token provided
+            via HTTP Authorization header.
+
+        Raises:
+            HTTPException: If the token is invalid or not provided.
+
+        Returns:
+            UserInfo: Information about the authenticated user.
+        """
+        # Extract the bearer token from the provided credentials
+        token = credentials.credentials
+
+        # Verify the token and get user information
+        user_info = AuthService.verify_token(token)
+
+        if not user_info:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        return user_info
--- a/backend/src/main.py
+++ b/backend/src/main.py
@@ -0,0 +1,118 @@
+from fastapi import FastAPI, Depends, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from fastapi.responses import RedirectResponse
+from src.models import TokenResponse, UserInfo
+from src.controller import AuthController
+from src.config import get_openid, get_settings
+
+# Initialize the FastAPI app
+app = FastAPI(title="Keycloak Auth API", version="1.0.0")
+
+# Get settings
+settings = get_settings()
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[settings.frontend_url],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize the HTTPBearer scheme for authentication
+bearer_scheme = HTTPBearer()
+
+# Configure client
+keycloak_openid = get_openid()
+
+
+# Define the root endpoint
+@app.get("/api")
+async def read_root():
+    """
+    Root endpoint that provides a welcome message and documentation link.
+    """
+    return AuthController.read_root()
+
+
+# Define the login endpoint
+@app.get("/api/login", response_class=RedirectResponse)
+async def login(request: Request):
+    """
+    Login endpoint to authenticate the user and return an access token.
+
+    Returns:
+        RedirectResponse: Contains the redirect URL upon successful authentication.
+    """
+    # Build the callback URI using the frontend URL (accessible from browser)
+    # This ensures the redirect works correctly through nginx proxy
+    redirect_uri = f"{settings.frontend_url}/api/callback"
+    
+    # Construct the authorization URL with external Keycloak URL
+    auth_url = (
+        f"{settings.keycloak_external_url}realms/{settings.keycloak_realm}"
+        f"/protocol/openid-connect/auth"
+        f"?client_id={settings.keycloak_client_id}"
+        f"&response_type=code"
+        f"&redirect_uri={redirect_uri}"
+        f"&scope=openid%20profile%20email"
+    )
+
+    return RedirectResponse(auth_url)
+
+
+# Define the callback endpoint
+@app.get("/api/callback", include_in_schema=False)
+async def callback(request: Request):
+    """
+    OAuth callback endpoint that exchanges the authorization code for a token
+    and sets it as an HTTP-only cookie.
+    """
+    # Extract the code from the URL
+    keycode = request.query_params.get('code')
+
+    return AuthController.login(str(keycode), request)
+
+
+# Define the auth/me endpoint to get current user from cookie
+@app.get("/api/auth/me", response_model=UserInfo)
+async def get_current_user(request: Request):
+    """
+    Get the current authenticated user from the session cookie.
+
+    Returns:
+        UserInfo: Information about the authenticated user.
+    """
+    return AuthController.get_current_user(request)
+
+
+# Define the logout endpoint
+@app.post("/api/auth/logout")
+async def logout(request: Request):
+    """
+    Logout endpoint that clears the authentication cookie.
+
+    Returns:
+        dict: Success message.
+    """
+    return AuthController.logout()
+
+
+# Define the protected endpoint (kept for API token-based access)
+@app.get("/api/protected", response_model=UserInfo)
+async def protected_endpoint(
+    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+):
+    """
+    Protected endpoint that requires a valid token for access.
+
+    Args:
+        credentials (HTTPAuthorizationCredentials):
+        Bearer token provided via HTTP Authorization header.
+
+    Returns:
+        UserInfo: Information about the authenticated user.
+    """
+    return AuthController.protected_endpoint(credentials)
--- a/backend/src/models.py
+++ b/backend/src/models.py
@@ -0,0 +1,18 @@
+from typing import Optional
+from pydantic import BaseModel, SecretStr
+
+
+class TokenRequest(BaseModel):
+    username: str
+    password: SecretStr
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+
+
+class UserInfo(BaseModel):
+    preferred_username: str
+    email: Optional[str] = None
+    full_name: Optional[str] = None
--- a/backend/src/service.py
+++ b/backend/src/service.py
@@ -0,0 +1,91 @@
+from fastapi import HTTPException, status, Request
+from keycloak.exceptions import KeycloakAuthenticationError, KeycloakPostError
+from keycloak import KeycloakOpenID
+from src.config import get_settings
+from src.models import UserInfo
+import logging
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+# Create a fresh KeycloakOpenID instance for token exchange
+def get_keycloak_openid():
+    return KeycloakOpenID(
+        server_url=settings.keycloak_server_url,
+        realm_name=settings.keycloak_realm,
+        client_id=settings.keycloak_client_id,
+        client_secret_key=settings.keycloak_client_secret,
+        verify=False
+    )
+
+
+class AuthService:
+    @staticmethod
+    def authenticate_user(keycode: str, request: Request) -> str:
+        """
+        Authenticate the user using Keycloak and return an access token.
+        """
+        try:
+            # Use the same redirect_uri that was used in the login endpoint
+            redirect_uri = f"{settings.frontend_url}/api/callback"
+            
+            logger.info(f"=== Token Exchange Debug ===")
+            logger.info(f"Keycloak Server URL: {settings.keycloak_server_url}")
+            logger.info(f"Realm: {settings.keycloak_realm}")
+            logger.info(f"Client ID: {settings.keycloak_client_id}")
+            logger.info(f"Client Secret (first 5 chars): {settings.keycloak_client_secret[:5]}...")
+            logger.info(f"Redirect URI: {redirect_uri}")
+            logger.info(f"Auth Code (first 10 chars): {keycode[:10]}...")
+            
+            # Get fresh KeycloakOpenID instance
+            keycloak_openid = get_keycloak_openid()
+            
+            token = keycloak_openid.token(
+                grant_type='authorization_code',
+                code=keycode,
+                redirect_uri=redirect_uri,
+            )
+            logger.info("Token exchange successful")
+            return token["access_token"]
+        except KeycloakAuthenticationError as exc:
+            logger.error(f"KeycloakAuthenticationError: {exc}")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=f"Invalid Login: {str(exc)}",
+            ) from exc
+        except KeycloakPostError as exc:
+            logger.error(f"KeycloakPostError: {exc}")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid Grant: {str(exc)}",
+            ) from exc
+        except Exception as exc:
+            logger.error(f"Unexpected error during token exchange: {exc}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Token exchange failed: {str(exc)}",
+            ) from exc
+
+    @staticmethod
+    def verify_token(token: str) -> UserInfo:
+        """
+        Verify the given token and return user information.
+        """
+        try:
+            keycloak_openid = get_keycloak_openid()
+            user_info = keycloak_openid.userinfo(token)
+            print(user_info)
+            if not user_info:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token"
+                )
+            return UserInfo(
+                preferred_username=user_info["preferred_username"],
+                email=user_info.get("email"),
+                full_name=user_info.get("name"),
+            )
+        except KeycloakAuthenticationError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Could not validate credentials",
+            ) from exc
--- a/docker-compose.dev.yaml
+++ b/docker-compose.dev.yaml
@@ -0,0 +1,45 @@
+# Development docker-compose
+# Use this for local development with hot reload
+# Run: docker-compose -f docker-compose.dev.yaml up
+
+services:
+  # ===========================================
+  # Keycloak Identity Provider
+  # ===========================================
+  keycloak:
+    image: quay.io/keycloak/keycloak:latest
+    container_name: keycloak
+    environment:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+    ports:
+      - "8081:8080"
+    command: start-dev
+    healthcheck:
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/localhost/8080 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '200 OK'"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  # ===========================================
+  # FastAPI Backend (with hot reload)
+  # ===========================================
+  fastapi-app:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    container_name: fastapi-app
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./backend:/app
+    env_file:
+      - .env
+    depends_on:
+      keycloak:
+        condition: service_healthy
+
+networks:
+  default:
+    name: keycloak-auth-network
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -0,0 +1,65 @@
+services:
+  # ===========================================
+  # Keycloak Identity Provider
+  # ===========================================
+  keycloak:
+    image: quay.io/keycloak/keycloak:latest
+    container_name: keycloak
+    environment:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      # Set hostname so tokens are issued with consistent issuer URL
+      KC_HOSTNAME: http://localhost:8081
+      KC_HOSTNAME_STRICT: false
+      KC_HTTP_ENABLED: true
+    ports:
+      - "8081:8080"
+    command: start-dev
+    volumes:
+      - keycloak_data:/opt/keycloak/data
+    healthcheck:
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/localhost/8080 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '200 OK'"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  # ===========================================
+  # FastAPI Backend
+  # ===========================================
+  fastapi-app:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    container_name: fastapi-app
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./backend:/app
+    env_file:
+      - .env
+    extra_hosts:
+      - "localhost:host-gateway"
+    depends_on:
+      keycloak:
+        condition: service_healthy
+
+  # ===========================================
+  # React Frontend
+  # ===========================================
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+    container_name: frontend
+    ports:
+      - "3000:80"
+    depends_on:
+      - fastapi-app
+
+networks:
+  default:
+    name: keycloak-auth-network
+
+volumes:
+  keycloak_data:
--- a/frontend/.env.example
+++ b/frontend/.env.example
@@ -0,0 +1,2 @@
+# Vite API URL (used during build)
+VITE_API_URL=/api
--- a/frontend/Dockerfile
+++ b/frontend/Dockerfile
@@ -0,0 +1,31 @@
+# Build stage
+FROM node:20-alpine AS build
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy source files
+COPY . .
+
+# Build the application
+RUN npm run build
+
+# Production stage
+FROM nginx:alpine
+
+# Copy custom nginx configuration
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+# Copy built assets from build stage
+COPY --from=build /app/dist /usr/share/nginx/html
+
+# Expose port 80
+EXPOSE 80
+
+# Start nginx
+CMD ["nginx", "-g", "daemon off;"]
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Keycloak Auth App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
--- a/frontend/nginx.conf
+++ b/frontend/nginx.conf
@@ -0,0 +1,70 @@
+server {
+    listen 80;
+    server_name localhost;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_proxied expired no-cache no-store private auth;
+    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml application/javascript application/json;
+
+    # Proxy API requests to backend
+    location /api {
+        proxy_pass http://fastapi-app:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host:$server_port;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host:$server_port;
+        proxy_cache_bypass $http_upgrade;
+        proxy_read_timeout 86400;
+        
+        # Ensure cookies are passed through
+        proxy_pass_header Set-Cookie;
+        proxy_cookie_path / /;
+    }
+
+    # Proxy Swagger docs
+    location /docs {
+        proxy_pass http://fastapi-app:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Proxy OpenAPI JSON
+    location /openapi.json {
+        proxy_pass http://fastapi-app:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Serve static files with caching
+    location /assets {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # SPA fallback - serve index.html for all other routes
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Health check endpoint
+    location /health {
+        access_log off;
+        return 200 "healthy\n";
+        add_header Content-Type text/plain;
+    }
+}
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.13.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.3",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^9.13.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.14",
+    "globals": "^15.11.0",
+    "postcss": "^8.4.47",
+    "tailwindcss": "^3.4.14",
+    "typescript": "~5.6.2",
+    "typescript-eslint": "^8.11.0",
+    "vite": "^5.4.10"
+  }
+}
--- a/frontend/postcss.config.js
+++ b/frontend/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -0,0 +1,30 @@
+import { Routes, Route } from 'react-router-dom'
+import Layout from '@/components/Layout'
+import HomePage from '@/pages/HomePage'
+import DashboardPage from '@/pages/DashboardPage'
+import ProtectedRoute from '@/components/ProtectedRoute'
+
+function App() {
+  return (
+    <Routes>
+      <Route
+        path="/"
+        element={
+          <Layout>
+            <HomePage />
+          </Layout>
+        }
+      />
+      <Route
+        path="/dashboard"
+        element={
+          <ProtectedRoute>
+            <DashboardPage />
+          </ProtectedRoute>
+        }
+      />
+    </Routes>
+  )
+}
+
+export default App
--- a/frontend/src/components/Layout.tsx
+++ b/frontend/src/components/Layout.tsx
@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react'
+import Navbar from './Navbar'
+
+interface LayoutProps {
+  children: ReactNode
+}
+
+export default function Layout({ children }: LayoutProps) {
+  return (
+    <div className="flex min-h-screen flex-col">
+      <Navbar />
+      <main className="flex-1">
+        <div className="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
+          {children}
+        </div>
+      </main>
+      <footer className="border-t border-gray-200 bg-white py-6">
+        <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+          <p className="text-center text-sm text-gray-500">
+            &copy; {new Date().getFullYear()} Keycloak Auth App. All rights
+            reserved.
+          </p>
+        </div>
+      </footer>
+    </div>
+  )
+}
--- a/frontend/src/components/Navbar.tsx
+++ b/frontend/src/components/Navbar.tsx
@@ -0,0 +1,72 @@
+import { Link } from 'react-router-dom'
+import { useAuth } from '@/hooks'
+
+export default function Navbar() {
+  const { user, isAuthenticated, login, logout } = useAuth()
+
+  return (
+    <nav className="border-b border-gray-200 bg-white shadow-sm">
+      <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+        <div className="flex h-16 items-center justify-between">
+          {/* Logo / Brand */}
+          <div className="flex items-center">
+            <Link
+              to="/"
+              className="flex items-center gap-2 text-xl font-bold text-primary-600 hover:text-primary-700"
+            >
+              <svg
+                className="h-8 w-8"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                strokeWidth={2}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
+                />
+              </svg>
+              <span>Auth App</span>
+            </Link>
+          </div>
+
+          {/* Navigation Links */}
+          <div className="flex items-center gap-4">
+            {isAuthenticated ? (
+              <>
+                <Link
+                  to="/dashboard"
+                  className="rounded-md px-3 py-2 text-sm font-medium text-gray-700 hover:bg-gray-100 hover:text-gray-900"
+                >
+                  Dashboard
+                </Link>
+                <div className="flex items-center gap-3">
+                  <span className="text-sm text-gray-600">
+                    Hello,{' '}
+                    <span className="font-medium text-gray-900">
+                      {user?.full_name || user?.preferred_username}
+                    </span>
+                  </span>
+                  <button
+                    onClick={logout}
+                    className="rounded-md bg-gray-100 px-4 py-2 text-sm font-medium text-gray-700 transition-colors hover:bg-gray-200"
+                  >
+                    Logout
+                  </button>
+                </div>
+              </>
+            ) : (
+              <button
+                onClick={login}
+                className="rounded-md bg-primary-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-primary-700"
+              >
+                Login
+              </button>
+            )}
+          </div>
+        </div>
+      </div>
+    </nav>
+  )
+}
--- a/frontend/src/components/ProtectedRoute.tsx
+++ b/frontend/src/components/ProtectedRoute.tsx
@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react'
+import { Navigate } from 'react-router-dom'
+import { useAuth } from '@/hooks'
+
+interface ProtectedRouteProps {
+  children: ReactNode
+}
+
+export default function ProtectedRoute({ children }: ProtectedRouteProps) {
+  const { isAuthenticated, isLoading } = useAuth()
+
+  if (isLoading) {
+    return (
+      <div className="flex min-h-[60vh] items-center justify-center">
+        <div className="flex flex-col items-center gap-4">
+          <div className="h-12 w-12 animate-spin rounded-full border-4 border-primary-200 border-t-primary-600" />
+          <p className="text-gray-600">Loading...</p>
+        </div>
+      </div>
+    )
+  }
+
+  if (!isAuthenticated) {
+    return <Navigate to="/" replace />
+  }
+
+  return <>{children}</>
+}
--- a/frontend/src/components/index.ts
+++ b/frontend/src/components/index.ts
@@ -0,0 +1,3 @@
+export { default as Layout } from './Layout'
+export { default as Navbar } from './Navbar'
+export { default as ProtectedRoute } from './ProtectedRoute'
--- a/frontend/src/context/AuthContext.tsx
+++ b/frontend/src/context/AuthContext.tsx
@@ -0,0 +1,64 @@
+import {
+  createContext,
+  useState,
+  useEffect,
+  useCallback,
+  type ReactNode,
+} from 'react'
+import type { User, AuthContextType } from '@/types'
+import { authService } from '@/services'
+
+export const AuthContext = createContext<AuthContextType | undefined>(undefined)
+
+interface AuthProviderProps {
+  children: ReactNode
+}
+
+export function AuthProvider({ children }: AuthProviderProps) {
+  const [user, setUser] = useState<User | null>(null)
+  const [isLoading, setIsLoading] = useState(true)
+
+  const refreshUser = useCallback(async () => {
+    try {
+      setIsLoading(true)
+      const currentUser = await authService.getCurrentUser()
+      setUser(currentUser)
+    } catch (error) {
+      console.error('Failed to refresh user:', error)
+      setUser(null)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [])
+
+  const login = useCallback(() => {
+    authService.login()
+  }, [])
+
+  const logout = useCallback(async () => {
+    try {
+      await authService.logout()
+      setUser(null)
+    } catch (error) {
+      console.error('Logout failed:', error)
+      // Still clear user on frontend even if backend logout fails
+      setUser(null)
+    }
+  }, [])
+
+  // Check authentication status on mount
+  useEffect(() => {
+    refreshUser()
+  }, [refreshUser])
+
+  const value: AuthContextType = {
+    user,
+    isLoading,
+    isAuthenticated: !!user,
+    login,
+    logout,
+    refreshUser,
+  }
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>
+}
--- a/frontend/src/context/index.ts
+++ b/frontend/src/context/index.ts
@@ -0,0 +1 @@
+export { AuthContext, AuthProvider } from './AuthContext'
--- a/frontend/src/hooks/index.ts
+++ b/frontend/src/hooks/index.ts
@@ -0,0 +1 @@
+export { useAuth } from './useAuth'
--- a/frontend/src/hooks/useAuth.ts
+++ b/frontend/src/hooks/useAuth.ts
@@ -0,0 +1,13 @@
+import { useContext } from 'react'
+import { AuthContext } from '@/context'
+import type { AuthContextType } from '@/types'
+
+export function useAuth(): AuthContextType {
+  const context = useContext(AuthContext)
+  
+  if (context === undefined) {
+    throw new Error('useAuth must be used within an AuthProvider')
+  }
+  
+  return context
+}
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -0,0 +1,7 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+body {
+  @apply bg-gray-50 text-gray-900 antialiased;
+}
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -0,0 +1,16 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import App from './App'
+import { AuthProvider } from '@/context/AuthContext'
+import './index.css'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <AuthProvider>
+        <App />
+      </AuthProvider>
+    </BrowserRouter>
+  </StrictMode>,
+)
--- a/frontend/src/pages/DashboardPage.tsx
+++ b/frontend/src/pages/DashboardPage.tsx
@@ -0,0 +1,245 @@
+import { useAuth } from '@/hooks'
+
+// Icons as components for cleaner code
+const DataServicesIcon = () => (
+  <svg className="w-16 h-16" viewBox="0 0 64 64" fill="none" stroke="currentColor" strokeWidth="2">
+    <rect x="12" y="8" width="40" height="48" rx="2" />
+    <line x1="20" y1="20" x2="44" y2="20" />
+    <line x1="20" y1="28" x2="44" y2="28" />
+    <line x1="20" y1="36" x2="44" y2="36" />
+    <line x1="20" y1="44" x2="36" y2="44" />
+    <rect x="36" y="40" width="12" height="12" rx="1" />
+    <line x1="40" y1="44" x2="44" y2="44" />
+    <line x1="40" y1="48" x2="44" y2="48" />
+  </svg>
+)
+
+const IntegrationIcon = () => (
+  <svg className="w-16 h-16" viewBox="0 0 64 64" fill="none" stroke="currentColor" strokeWidth="2">
+    <rect x="8" y="16" width="20" height="14" rx="2" />
+    <rect x="36" y="16" width="20" height="14" rx="2" />
+    <rect x="22" y="38" width="20" height="14" rx="2" />
+    <line x1="18" y1="30" x2="18" y2="38" />
+    <line x1="18" y1="38" x2="32" y2="38" />
+    <line x1="46" y1="30" x2="46" y2="38" />
+    <line x1="46" y1="38" x2="32" y2="38" />
+  </svg>
+)
+
+const IntelligenceIcon = () => (
+  <svg className="w-16 h-16" viewBox="0 0 64 64" fill="none" stroke="currentColor" strokeWidth="2">
+    <circle cx="28" cy="28" r="14" />
+    <line x1="38" y1="38" x2="52" y2="52" strokeWidth="4" strokeLinecap="round" />
+    <path d="M22 28 L26 32 L34 24" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+  </svg>
+)
+
+const UserExperienceIcon = () => (
+  <svg className="w-16 h-16" viewBox="0 0 64 64" fill="none" stroke="currentColor" strokeWidth="2">
+    <circle cx="32" cy="20" r="8" />
+    <circle cx="16" cy="36" r="4" />
+    <circle cx="48" cy="36" r="4" />
+    <circle cx="24" cy="52" r="4" />
+    <circle cx="40" cy="52" r="4" />
+    <line x1="32" y1="28" x2="32" y2="36" />
+    <line x1="32" y1="36" x2="16" y2="36" />
+    <line x1="32" y1="36" x2="48" y2="36" />
+    <line x1="20" y1="40" x2="24" y2="48" />
+    <line x1="44" y1="40" x2="40" y2="48" />
+  </svg>
+)
+
+const ManagementIcon = () => (
+  <svg className="w-16 h-16" viewBox="0 0 64 64" fill="none" stroke="currentColor" strokeWidth="2">
+    <circle cx="32" cy="32" r="12" />
+    <path d="M32 16 L32 20" />
+    <path d="M32 44 L32 48" />
+    <path d="M16 32 L20 32" />
+    <path d="M44 32 L48 32" />
+    <path d="M20.7 20.7 L23.5 23.5" />
+    <path d="M40.5 40.5 L43.3 43.3" />
+    <path d="M20.7 43.3 L23.5 40.5" />
+    <path d="M40.5 23.5 L43.3 20.7" />
+    <rect x="26" y="28" width="12" height="10" rx="1" />
+    <path d="M29 28 L29 26 L35 26 L35 28" />
+    <line x1="29" y1="32" x2="35" y2="32" />
+  </svg>
+)
+
+const TrustworthinessIcon = () => (
+  <svg className="w-16 h-16" viewBox="0 0 64 64" fill="none" stroke="currentColor" strokeWidth="2">
+    <path d="M12 36 C12 36 20 28 32 36 C44 44 52 36 52 36" strokeLinecap="round" />
+    <path d="M12 36 L24 48 L32 36" strokeLinecap="round" strokeLinejoin="round" />
+    <path d="M52 36 L40 48 L32 36" strokeLinecap="round" strokeLinejoin="round" />
+  </svg>
+)
+
+export default function DashboardPage() {
+  const { user, logout } = useAuth()
+
+  return (
+    <div className="min-h-screen bg-white">
+      {/* Header */}
+      <header className="py-6 text-center">
+        <h1 className="text-3xl font-semibold text-teal-700">
+          Digital Twin Requirements Tool
+        </h1>
+      </header>
+
+      {/* Top Bar */}
+      <div className="border-y border-gray-200 py-3 px-8">
+        <div className="flex items-center justify-between max-w-7xl mx-auto">
+          {/* Breadcrumb */}
+          <div className="text-sm">
+            <span className="text-gray-600">Projects</span>
+            <span className="mx-2 text-gray-400">»</span>
+            <span className="font-semibold text-gray-900">PeTWIN</span>
+          </div>
+
+          {/* Language Toggle */}
+          <div className="flex items-center gap-2 text-sm text-gray-600">
+            <span>English</span>
+            <div className="relative inline-flex h-5 w-10 items-center rounded-full bg-gray-300">
+              <span className="inline-block h-4 w-4 transform rounded-full bg-white shadow-sm translate-x-0.5" />
+            </div>
+            <span>Portuguese</span>
+          </div>
+
+          {/* Admin Panel Button */}
+          <button className="px-4 py-1.5 border border-gray-400 rounded text-sm font-medium text-gray-700 hover:bg-gray-50">
+            Admin Panel
+          </button>
+
+          {/* User Info */}
+          <div className="flex items-center gap-3">
+            <div className="flex items-center gap-2">
+              <svg className="w-5 h-5 text-gray-600" fill="currentColor" viewBox="0 0 20 20">
+                <path fillRule="evenodd" d="M10 9a3 3 0 100-6 3 3 0 000 6zm-7 9a7 7 0 1114 0H3z" clipRule="evenodd" />
+              </svg>
+              <span className="text-sm text-gray-700">
+                {user?.full_name || user?.preferred_username || 'User'}{' '}
+                <span className="text-gray-500">(admin)</span>
+              </span>
+            </div>
+            <button
+              onClick={logout}
+              className="px-3 py-1 border border-gray-400 rounded text-sm text-gray-700 hover:bg-gray-50"
+            >
+              Logout
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {/* Main Content */}
+      <div className="max-w-7xl mx-auto px-8 py-8">
+        <div className="flex gap-12">
+          {/* Left Sidebar */}
+          <div className="w-64 flex-shrink-0">
+            {/* Requirements Search */}
+            <div className="mb-8">
+              <h2 className="text-lg font-bold text-gray-800 mb-1">Requirements Search</h2>
+              <p className="text-sm text-teal-600">
+                Search for specific elements by name or symbol.
+              </p>
+            </div>
+
+            {/* Create a Requirement */}
+            <div className="mb-8">
+              <h2 className="text-lg font-bold text-gray-800 mb-1">Create a Requirement</h2>
+              <p className="text-sm text-teal-600">
+                Register a new Requirement.
+              </p>
+            </div>
+
+            {/* Last Viewed Requirement */}
+            <div className="mb-8">
+              <h2 className="text-lg font-bold text-gray-800 mb-1">Last Viewed Requirement:</h2>
+              <p className="text-sm text-gray-600 mb-1">No requirement accessed yet</p>
+              <a href="#" className="text-sm text-teal-600 hover:underline">
+                View More
+              </a>
+            </div>
+
+            {/* My Requirements */}
+            <div className="mb-8">
+              <h2 className="text-lg font-bold text-gray-800 mb-1">My Requirements</h2>
+              <p className="text-sm text-teal-600">
+                View your requirements and their properties.
+              </p>
+            </div>
+
+            {/* Requirement Report */}
+            <div className="mb-8">
+              <h2 className="text-lg font-bold text-gray-800 mb-1">Requirement Report</h2>
+              <p className="text-sm text-teal-600">
+                Generate the current status of this projects requirements in PDF format
+              </p>
+            </div>
+          </div>
+
+          {/* Right Content - Quick Search Filters */}
+          <div className="flex-1">
+            <h2 className="text-xl font-semibold text-gray-700 mb-6 text-center">
+              Quick Search Filters
+            </h2>
+
+            {/* Grid Layout matching the screenshot */}
+            <div className="grid grid-cols-4 gap-0 max-w-2xl mx-auto">
+              {/* Row 1 */}
+              {/* Data Services - spans 2 rows */}
+              <div className="row-span-2 bg-blue-200 border border-blue-300 flex flex-col items-center justify-center p-4 cursor-pointer hover:bg-blue-300 transition-colors min-h-[200px]">
+                <div className="text-blue-800">
+                  <DataServicesIcon />
+                </div>
+                <span className="mt-3 text-sm font-semibold text-blue-900">Data Services</span>
+              </div>
+
+              {/* Integration - 1 row */}
+              <div className="bg-amber-200 border border-amber-300 flex flex-col items-center justify-center p-4 cursor-pointer hover:bg-amber-300 transition-colors min-h-[100px]">
+                <div className="text-amber-800">
+                  <IntegrationIcon />
+                </div>
+                <span className="mt-2 text-sm font-semibold text-amber-900">Integration</span>
+              </div>
+
+              {/* Intelligence - spans 2 rows */}
+              <div className="row-span-2 bg-purple-200 border border-purple-300 flex flex-col items-center justify-center p-4 cursor-pointer hover:bg-purple-300 transition-colors min-h-[200px]">
+                <div className="text-purple-800">
+                  <IntelligenceIcon />
+                </div>
+                <span className="mt-3 text-sm font-semibold text-purple-900">Intelligence</span>
+              </div>
+
+              {/* User Experience - spans 2 rows */}
+              <div className="row-span-2 bg-green-200 border border-green-300 flex flex-col items-center justify-center p-4 cursor-pointer hover:bg-green-300 transition-colors min-h-[200px]">
+                <div className="text-green-800">
+                  <UserExperienceIcon />
+                </div>
+                <span className="mt-3 text-sm font-semibold text-green-900">User Experience</span>
+              </div>
+
+              {/* Row 2 - Management and Trustworthiness */}
+              {/* Management - 1 row, spans 1 col */}
+              <div className="bg-red-200 border border-red-300 flex flex-col items-center justify-center p-4 cursor-pointer hover:bg-red-300 transition-colors min-h-[100px]">
+                <div className="text-red-800">
+                  <ManagementIcon />
+                </div>
+                <span className="mt-2 text-sm font-semibold text-red-900">Management</span>
+              </div>
+
+              {/* Trustworthiness - 1 row */}
+              <div className="bg-green-100 border border-green-300 flex flex-col items-center justify-center p-4 cursor-pointer hover:bg-green-200 transition-colors min-h-[100px]">
+                <div className="text-red-400">
+                  <TrustworthinessIcon />
+                </div>
+                <span className="mt-2 text-sm font-semibold text-red-600">Trustworthiness</span>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
--- a/frontend/src/pages/HomePage.tsx
+++ b/frontend/src/pages/HomePage.tsx
@@ -0,0 +1,151 @@
+import { useAuth } from '@/hooks'
+
+export default function HomePage() {
+  const { isAuthenticated, login, isLoading } = useAuth()
+
+  if (isLoading) {
+    return (
+      <div className="flex min-h-[60vh] items-center justify-center">
+        <div className="h-12 w-12 animate-spin rounded-full border-4 border-primary-200 border-t-primary-600" />
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex min-h-[60vh] flex-col items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold tracking-tight text-gray-900 sm:text-5xl md:text-6xl">
+          Welcome to{' '}
+          <span className="text-primary-600">Keycloak Auth</span>
+        </h1>
+        <p className="mx-auto mt-6 max-w-2xl text-lg text-gray-600">
+          A secure authentication system powered by Keycloak and FastAPI. Login
+          with your Keycloak credentials to access protected resources.
+        </p>
+
+        {!isAuthenticated && (
+          <div className="mt-10">
+            <button
+              onClick={login}
+              className="inline-flex items-center gap-2 rounded-lg bg-primary-600 px-8 py-4 text-lg font-semibold text-white shadow-lg transition-all hover:bg-primary-700 hover:shadow-xl focus:outline-none focus:ring-4 focus:ring-primary-300"
+            >
+              <svg
+                className="h-6 w-6"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                strokeWidth={2}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M11 16l-4-4m0 0l4-4m-4 4h14m-5 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h7a3 3 0 013 3v1"
+                />
+              </svg>
+              Login with Keycloak
+            </button>
+          </div>
+        )}
+
+        {isAuthenticated && (
+          <div className="mt-10">
+            <a
+              href="/dashboard"
+              className="inline-flex items-center gap-2 rounded-lg bg-primary-600 px-8 py-4 text-lg font-semibold text-white shadow-lg transition-all hover:bg-primary-700 hover:shadow-xl focus:outline-none focus:ring-4 focus:ring-primary-300"
+            >
+              <svg
+                className="h-6 w-6"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                strokeWidth={2}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M4 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2V6zM14 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2V6zM4 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2v-2zM14 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2v-2z"
+                />
+              </svg>
+              Go to Dashboard
+            </a>
+          </div>
+        )}
+      </div>
+
+      {/* Features Section */}
+      <div className="mt-20 grid gap-8 sm:grid-cols-2 lg:grid-cols-3">
+        <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm">
+          <div className="mb-4 flex h-12 w-12 items-center justify-center rounded-lg bg-primary-100">
+            <svg
+              className="h-6 w-6 text-primary-600"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              strokeWidth={2}
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
+              />
+            </svg>
+          </div>
+          <h3 className="mb-2 text-lg font-semibold text-gray-900">
+            Secure Authentication
+          </h3>
+          <p className="text-gray-600">
+            HTTP-only cookies protect your tokens from XSS attacks.
+          </p>
+        </div>
+
+        <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm">
+          <div className="mb-4 flex h-12 w-12 items-center justify-center rounded-lg bg-primary-100">
+            <svg
+              className="h-6 w-6 text-primary-600"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              strokeWidth={2}
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"
+              />
+            </svg>
+          </div>
+          <h3 className="mb-2 text-lg font-semibold text-gray-900">
+            Keycloak Integration
+          </h3>
+          <p className="text-gray-600">
+            Enterprise-grade identity management with Keycloak SSO.
+          </p>
+        </div>
+
+        <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm">
+          <div className="mb-4 flex h-12 w-12 items-center justify-center rounded-lg bg-primary-100">
+            <svg
+              className="h-6 w-6 text-primary-600"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              strokeWidth={2}
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M13 10V3L4 14h7v7l9-11h-7z"
+              />
+            </svg>
+          </div>
+          <h3 className="mb-2 text-lg font-semibold text-gray-900">
+            FastAPI Backend
+          </h3>
+          <p className="text-gray-600">
+            High-performance Python backend with automatic API documentation.
+          </p>
+        </div>
+      </div>
+    </div>
+  )
+}
--- a/frontend/src/pages/index.ts
+++ b/frontend/src/pages/index.ts
@@ -0,0 +1,2 @@
+export { default as HomePage } from './HomePage'
+export { default as DashboardPage } from './DashboardPage'
--- a/frontend/src/services/authService.ts
+++ b/frontend/src/services/authService.ts
@@ -0,0 +1,67 @@
+import type { User } from '@/types'
+
+const API_BASE_URL = '/api'
+
+class AuthService {
+  /**
+   * Get the current authenticated user from the session cookie.
+   * Returns null if not authenticated.
+   */
+  async getCurrentUser(): Promise<User | null> {
+    try {
+      const response = await fetch(`${API_BASE_URL}/auth/me`, {
+        method: 'GET',
+        credentials: 'include',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      })
+
+      if (!response.ok) {
+        if (response.status === 401) {
+          return null
+        }
+        throw new Error(`HTTP error! status: ${response.status}`)
+      }
+
+      const user: User = await response.json()
+      return user
+    } catch (error) {
+      console.error('Failed to get current user:', error)
+      return null
+    }
+  }
+
+  /**
+   * Logout the current user by clearing the session cookie.
+   */
+  async logout(): Promise<void> {
+    try {
+      const response = await fetch(`${API_BASE_URL}/auth/logout`, {
+        method: 'POST',
+        credentials: 'include',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      })
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`)
+      }
+    } catch (error) {
+      console.error('Logout failed:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Redirect to the login endpoint to initiate OAuth flow.
+   */
+  login(): void {
+    // In development with Vite proxy, we can use relative URL
+    // In production, this will be proxied by nginx
+    window.location.href = `${API_BASE_URL}/login`
+  }
+}
+
+export const authService = new AuthService()
--- a/frontend/src/services/index.ts
+++ b/frontend/src/services/index.ts
@@ -0,0 +1 @@
+export { authService } from './authService'
--- a/frontend/src/types/auth.ts
+++ b/frontend/src/types/auth.ts
@@ -0,0 +1,14 @@
+export interface User {
+  preferred_username: string
+  email: string | null
+  full_name: string | null
+}
+
+export interface AuthContextType {
+  user: User | null
+  isLoading: boolean
+  isAuthenticated: boolean
+  login: () => void
+  logout: () => Promise<void>
+  refreshUser: () => Promise<void>
+}
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -0,0 +1 @@
+export * from './auth'
--- a/frontend/src/vite-env.d.ts
+++ b/frontend/src/vite-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+declare module '*.css' {
+  const content: string
+  export default content
+}
--- a/frontend/tailwind.config.js
+++ b/frontend/tailwind.config.js
@@ -0,0 +1,27 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50: '#eff6ff',
+          100: '#dbeafe',
+          200: '#bfdbfe',
+          300: '#93c5fd',
+          400: '#60a5fa',
+          500: '#3b82f6',
+          600: '#2563eb',
+          700: '#1d4ed8',
+          800: '#1e40af',
+          900: '#1e3a8a',
+          950: '#172554',
+        },
+      },
+    },
+  },
+  plugins: [],
+}
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+
+    /* Path aliases */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"]
+}
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -0,0 +1,22 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import path from 'path'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: {
+    port: 3000,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:8080',
+        changeOrigin: true,
+      },
+    },
+  },
+})
				`@@ -0,0 +1 @@`
				`export { AuthContext, AuthProvider } from './AuthContext'`
				`@@ -0,0 +1 @@`
				`export { authService } from './authService'`