Init traefik auth proxy

Author: r-brown

traefik-auth-proxy/Dockerfile

@@ -0,0 +1,33 @@
+FROM python:3-alpine
+
+# Define build arguments
+ARG USER_ID=1064
+ARG GROUP_ID=1064
+ARG USER_NAME=l64user
+ARG GROUP_NAME=l64group
+
+# Create group and user with the specified IDs
+RUN addgroup -g ${GROUP_ID} ${GROUP_NAME} && \
+    adduser -D -u ${USER_ID} -G ${GROUP_NAME} ${USER_NAME}
+
+# Set working directory
+WORKDIR /home/${USER_NAME}
+
+# Copy the requirements file into the container at the working directory
+COPY --chown=${USER_NAME}:${GROUP_NAME} requirements.txt .
+
+# Copy the main FastAPI application file
+COPY --chown=${USER_NAME}:${GROUP_NAME} traefik-auth-proxy.py .
+
+# Install any needed packages specified in requirements.txt
+RUN python -m pip install --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Make port 8081 available outside this container
+EXPOSE 8081
+
+# Set user context
+USER ${USER_NAME}
+
+# Run the FastAPI application using Uvicorn
+CMD ["uvicorn", "traefik-auth-proxy:app", "--host", "0.0.0.0", "--port", "8081"]

traefik-auth-proxy/README.md

@@ -0,0 +1,45 @@
+<p align="center"><img src="https://raw.githubusercontent.com/Labs64/.github/refs/heads/master/assets/labs64-io-ecosystem.png"></p>
+
+## Traefik Auth (M2M) Middleware
+
+This repository contains a custom Traefik ForwardAuth middleware. The middleware is designed to verify M2M (Machine-to-Machine) JWT tokens issued by Keycloak and enforce path-based role-based access control (RBAC) for microservices deployed on Kubernetes.
+
+It receives incoming requests from Traefik, validates the JWT token, extracts user roles, and checks them against a configurable path/role mapping. If the request is authorized, it allows Traefik to forward the request to the backend service. Otherwise, it returns a `401 Unauthorized` or `403 Forbidden` response.
+
+## Features
+
+- JWT Verification: Validates tokens issued by Keycloak using public keys from the `.well-known` endpoint.
+- Role-Based Access Control (RBAC): Enforces access based on roles assigned to the user/client.
+- Configurable Role Mapping: Allows administrators to define a mapping of URL paths to required roles.
+- FastAPI Backend: A lightweight and performant backend for handling authentication logic.
+
+## Prerequisites
+
+- A running Kubernetes cluster.
+- Traefik installed as an Ingress Controller in your cluster.
+- A configured Keycloak instance.
+- Docker for building the middleware container image.
+
+## Configuration
+
+The middleware is configured using environment variables.
+
+- `KEYCLOAK_URL`: The base URL of your Keycloak instance (e.g., http://keycloak.default.svc.cluster.local:8080).
+- `KEYCLOAK_REALM`: The name of the realm in Keycloak (e.g., labs64io).
+- `KEYCLOAK_AUDIENCE`: The audience claim to verify in the JWT (e.g., labs64io_client).
+- `ROLE_MAPPING`: A JSON string defining the path-to-role mapping. This can be passed as a ConfigMap in a production environment.
+
+## Usage
+
+- Once deployed, Traefik will intercept any request to *whoami.example.com* and forward it to the auth-middleware for authentication.
+- For a request to be successful, it must include a valid JWT in the Authorization header with the format `Bearer <token>`. The roles contained in the JWT must match the required roles for the requested path as defined in your role mapping.
+- The role mapping is a key part of the middleware's logic. You would define a dictionary that maps a path prefix to a list of required roles.
+
+### For example:
+
+- A request to `/api/admin` would require the `admin` role.
+- A request to `/api/users` would require either the `user` or `admin` role.
+
+## License
+
+This project is licensed under the MIT License.

traefik-auth-proxy/justfile

@@ -0,0 +1,34 @@
+APP_NAME := "traefik-auth-proxy"
+
+# build application
+docker:
+    docker build -t {{APP_NAME}}:latest .
+    docker tag {{APP_NAME}}:latest localhost:5005/{{APP_NAME}}:latest
+    docker push localhost:5005/{{APP_NAME}}:latest
+    docker images | grep "{{APP_NAME}}"
+
+# run docker image
+run: docker
+    docker run -p 8081:8081 \
+      -e KEYCLOAK_URL="http://host.docker.internal:8080" \
+      -e KEYCLOAK_REALM="labs64io" \
+      -e KEYCLOAK_AUDIENCE="account" \
+      {{APP_NAME}}:latest
+
+# open documentation
+docu:
+    open "http://localhost:8081/redoc"
+    open "http://localhost:8081/docs"
+
+
+# open Keycloak well-known configuration
+test_show_well_known:
+    open "http://keycloak.localhost/realms/labs64io/.well-known/openid-configuration"
+
+# generate JWT token
+test_generate_jwt_token:
+    curl --location --request POST 'http://keycloak.localhost/realms/labs64io/protocol/openid-connect/token' \
+    --header 'Content-Type: application/x-www-form-urlencoded' \
+    --data-urlencode 'grant_type=client_credentials' \
+    --data-urlencode 'client_id=labs64io-api-gateway' \
+    --data-urlencode 'client_secret=mTEqlt1dDzcVyEOzFjBZV4X8jvEkaQnc'

traefik-auth-proxy/requirements.txt

@@ -0,0 +1,4 @@
+fastapi==0.116.1
+uvicorn==0.35.0
+python-jose==3.5.0
+requests==2.32.4

traefik-auth-proxy/traefik-auth-proxy.py

@@ -0,0 +1,156 @@
+import os
+import logging
+from typing import Dict, Any, List
+
+import requests
+from fastapi import FastAPI, Request, HTTPException, status
+from jose import jwt
+from jose.exceptions import JWTError, ExpiredSignatureError
+
+# --- Configuration ---
+KEYCLOAK_URL = os.getenv("KEYCLOAK_URL", "http://keycloak.localhost")
+KEYCLOAK_REALM = os.getenv("KEYCLOAK_REALM", "labs64io")
+KEYCLOAK_AUDIENCE = os.getenv("KEYCLOAK_AUDIENCE", "account")
+
+# --- Path-to-role mapping ---
+ROLE_MAPPING: Dict[str, List[str]] = {
+    "/api/v1/admin": ["admin-role"],
+    "/api/v1/auditflow": ["auditflow-role", "admin-role", "default-roles-labs64io"],
+    "/api/v1/ecommerce": ["ecommerce-role", "admin-role"],
+    "/public": ["authenticated-user"]
+}
+
+# JWKS Cache
+JWKS_CACHE: Dict[str, Any] = {}
+
+# Logging configuration
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+app_logger = logging.getLogger(__name__)
+app_logger.setLevel(logging.DEBUG)
+
+# FastAPI app
+app = FastAPI(
+    title="Traefik Auth (M2M) Middleware",
+    description="Custom Traefik ForwardAuth service to verify Keycloak JWT tokens and enforce role-based access control.",
+    version="1.0.0"
+)
+
+# --- JWKS and JWT Validation Functions ---
+
+def get_jwks() -> Dict[str, Any]:
+    """
+    Fetches JWKS from Keycloak or returns it from cache.
+    """
+    if JWKS_CACHE:
+        app_logger.info("get_jwks::using cached JWKS")
+        return JWKS_CACHE
+
+    jwks_url = f"{KEYCLOAK_URL}/realms/{KEYCLOAK_REALM}/protocol/openid-connect/certs"
+    try:
+        app_logger.info(f"get_jwks::fetching JWKS from: {jwks_url}")
+        response = requests.get(jwks_url)
+        response.raise_for_status()
+        # Cache JWKS
+        JWKS_CACHE.update(response.json())
+        return JWKS_CACHE
+    except requests.RequestException as e:
+        app_logger.error(f"get_jwks::Failed to fetch JWKS: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to retrieve public keys: {e}"
+        )
+
+def verify_token(token: str) -> Dict[str, Any]:
+    """
+    Verifies the JWT token using JWKS and returns the payload.
+    """
+    try:
+        header = jwt.get_unverified_header(token)
+        kid = header.get("kid")
+        if not kid:
+            raise HTTPException(status_code=401, detail="JWT header is missing 'kid'")
+
+        jwks = get_jwks()
+        payload = jwt.decode(
+            token,
+            jwks,
+            algorithms=["RS256"],
+            audience=KEYCLOAK_AUDIENCE
+        )
+        return payload
+
+    except ExpiredSignatureError:
+        app_logger.error("verify_token::Token has expired")
+        raise HTTPException(status_code=401, detail="Token has expired")
+    except JWTError as e:
+        app_logger.error(f"verify_token::Invalid token: {e}")
+        raise HTTPException(status_code=401, detail=f"Invalid token: {e}")
+    except Exception as e:
+        app_logger.error(f"verify_token::Unexpected error: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Token verification failed: {e}")
+
+
+# --- FastAPI Endpoint for Traefik ForwardAuth ---
+
+@app.get("/auth")
+@app.post("/auth")
+async def authenticate(request: Request):
+    """
+    Traefik ForwardAuth endpoint. Validates JWT and enforces RBAC.
+    """
+    auth_header = request.headers.get("Authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Authorization header is missing or malformed")
+
+    token = auth_header.split(" ")[1]
+    payload = verify_token(token)
+    app_logger.debug(f"JWT Decoded Payload: {payload}")
+
+    token_roles = set()
+    realm_access = payload.get("realm_access", {})
+    if isinstance(realm_access, dict):
+        token_roles.update(realm_access.get("roles", []))
+
+    resource_access = payload.get("resource_access", {})
+    client_roles = resource_access.get(KEYCLOAK_AUDIENCE, {}).get("roles", [])
+    token_roles.update(client_roles)
+
+    if not token_roles:
+        raise HTTPException(status_code=403, detail="Token does not contain any roles")
+
+    forwarded_uri = request.headers.get("X-Forwarded-Uri", "/")
+
+    required_roles: List[str] = []
+    best_match = ""
+    app_logger.info(f"Evaluating path: {forwarded_uri} with token roles: {token_roles}")
+    for path_prefix, roles in ROLE_MAPPING.items():
+        if forwarded_uri.startswith(path_prefix):
+            app_logger.debug(f"Matched path prefix: {path_prefix} with roles: {roles}")
+            if len(path_prefix) > len(best_match):
+                best_match = path_prefix
+                required_roles = roles
+
+    if not required_roles:
+        app_logger.warning(f"No access control rules configured for path: {forwarded_uri}")
+        raise HTTPException(
+            status_code=403,
+            detail=f"Path '{forwarded_uri}' is not configured for access control"
+        )
+
+    app_logger.info(f"Path matched: {best_match}, required roles: {required_roles}")
+
+    if not token_roles.intersection(required_roles):
+        app_logger.warning(
+            f"Access denied for path '{forwarded_uri}'. "
+            f"Token roles: {token_roles}, required: {required_roles}"
+        )
+        raise HTTPException(
+            status_code=403,
+            detail=f"Insufficient permissions. Required roles: {required_roles}"
+        )
+
+    return {
+        "message": "Authentication successful",
+        "user_id": payload.get("sub"),
+        "roles": list(token_roles)
+    }