Keycloak middleware refactor and decorator additions

Author: dominiquekleeven

frontend/src/pages/pages-config-list.ts

@@ -105,7 +105,7 @@ export class PageConfigList extends LitElement {
             this.loading = false;
         } catch (error) {
             console.error('Failed to fetch model configs:', error);
-            this.error = `Failed to retrieve forecast configurations`;
+            this.error = `Failed to retrieve the forecast configurations`;
             this.modelConfigs = [];
             this.configAssets = [];
             this.loading = false;
@@ -134,8 +134,8 @@ export class PageConfigList extends LitElement {
                 await APIService.deleteModelConfig(this.realm, config.id);
                 this.modelConfigs = this.modelConfigs?.filter((c) => c.id !== config.id);
             } catch (error) {
-                showSnackbar(undefined, `Failed to delete config: ${error}`);
-                console.error('Failed to delete config:', error);
+                showSnackbar(undefined, `Failed to delete the config`);
+                console.error('Failed to delete the config:', error);
             }
         }
     }

src/service_ml_forecast/api/model_config_route.py

@@ -28,11 +28,21 @@
 from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import JSONResponse
 
-from service_ml_forecast.dependencies import get_config_service, oauth2_scheme
+from service_ml_forecast.clients.openremote.client_roles import ClientRoles
+from service_ml_forecast.dependencies import OAUTH2_SCHEME, OPENREMOTE_KC_RESOURCE, get_config_service
+from service_ml_forecast.middlewares.keycloak.decorators import realm_allowed, roles_allowed
+from service_ml_forecast.middlewares.keycloak.middleware import KeycloakMiddleware
+from service_ml_forecast.middlewares.keycloak.models import UserContext
 from service_ml_forecast.models.model_config import ModelConfig
 from service_ml_forecast.services.model_config_service import ModelConfigService
 
-router = APIRouter(prefix="/api/{realm}/configs", tags=["Forecast Configs"])
+router = APIRouter(
+    prefix="/api/{realm}/configs",
+    tags=["Forecast Configs"],
+    dependencies=[
+        Depends(OAUTH2_SCHEME),
+    ],
+)
 
 
 @router.post(
@@ -42,10 +52,13 @@
         HTTPStatus.OK: {"description": "Model config has been created"},
         HTTPStatus.CONFLICT: {"description": "Model config already exists"},
         HTTPStatus.UNAUTHORIZED: {"description": "Unauthorized"},
+        HTTPStatus.FORBIDDEN: {"description": "Forbidden - insufficient permissions"},
     },
 )
+@realm_allowed
+@roles_allowed(resource=OPENREMOTE_KC_RESOURCE, roles=[ClientRoles.WRITE_ADMIN_ROLE])
 async def create_model_config(
-    token: Annotated[str, Depends(oauth2_scheme)],
+    user: Annotated[UserContext, Depends(KeycloakMiddleware.get_user_context)],
     realm: str,
     model_config: ModelConfig,
     config_service: ModelConfigService = Depends(get_config_service),
@@ -60,10 +73,13 @@ async def create_model_config(
         HTTPStatus.OK: {"description": "Model config has been retrieved"},
         HTTPStatus.NOT_FOUND: {"description": "Model config not found"},
         HTTPStatus.UNAUTHORIZED: {"description": "Unauthorized"},
+        HTTPStatus.FORBIDDEN: {"description": "Forbidden - insufficient permissions"},
     },
 )
+@realm_allowed
+@roles_allowed(resource=OPENREMOTE_KC_RESOURCE, roles=[ClientRoles.READ_ADMIN_ROLE])
 async def get_model_config(
-    token: Annotated[str, Depends(oauth2_scheme)],
+    user: Annotated[UserContext, Depends(KeycloakMiddleware.get_user_context)],
     realm: str,
     id: UUID,
     config_service: ModelConfigService = Depends(get_config_service),
@@ -77,10 +93,13 @@ async def get_model_config(
     responses={
         HTTPStatus.OK: {"description": "List of model configs has been retrieved"},
         HTTPStatus.UNAUTHORIZED: {"description": "Unauthorized"},
+        HTTPStatus.FORBIDDEN: {"description": "Forbidden - insufficient permissions"},
     },
 )
+@realm_allowed
+@roles_allowed(resource=OPENREMOTE_KC_RESOURCE, roles=[ClientRoles.READ_ADMIN_ROLE])
 async def get_model_configs(
-    token: Annotated[str, Depends(oauth2_scheme)],
+    user: Annotated[UserContext, Depends(KeycloakMiddleware.get_user_context)],
     realm: str,
     config_service: ModelConfigService = Depends(get_config_service),
 ) -> list[ModelConfig]:
@@ -94,10 +113,13 @@ async def get_model_configs(
         HTTPStatus.OK: {"description": "Model config has been updated"},
         HTTPStatus.NOT_FOUND: {"description": "Model config not found"},
         HTTPStatus.UNAUTHORIZED: {"description": "Unauthorized"},
+        HTTPStatus.FORBIDDEN: {"description": "Forbidden - insufficient permissions"},
     },
 )
+@realm_allowed
+@roles_allowed(resource=OPENREMOTE_KC_RESOURCE, roles=[ClientRoles.WRITE_ADMIN_ROLE])
 async def update_model_config(
-    token: Annotated[str, Depends(oauth2_scheme)],
+    user: Annotated[UserContext, Depends(KeycloakMiddleware.get_user_context)],
     realm: str,
     id: UUID,
     model_config: ModelConfig,
@@ -116,10 +138,13 @@ async def update_model_config(
         HTTPStatus.OK: {"description": "Model config has been deleted"},
         HTTPStatus.NOT_FOUND: {"description": "Model config not found"},
         HTTPStatus.UNAUTHORIZED: {"description": "Unauthorized"},
+        HTTPStatus.FORBIDDEN: {"description": "Forbidden - insufficient permissions"},
     },
 )
+@realm_allowed
+@roles_allowed(resource=OPENREMOTE_KC_RESOURCE, roles=[ClientRoles.WRITE_ADMIN_ROLE])
 async def delete_model_config(
-    token: Annotated[str, Depends(oauth2_scheme)],
+    user: Annotated[UserContext, Depends(KeycloakMiddleware.get_user_context)],
     realm: str,
     id: UUID,
     config_service: ModelConfigService = Depends(get_config_service),

src/service_ml_forecast/clients/openremote/client_roles.py

@@ -0,0 +1,17 @@
+class ClientRoles:
+    READ_LOGS_ROLE = "read:logs"
+    READ_USERS_ROLE = "read:users"
+    READ_ADMIN_ROLE = "read:admin"
+    READ_MAP_ROLE = "read:map"
+    READ_ASSETS_ROLE = "read:assets"
+    READ_RULES_ROLE = "read:rules"
+    READ_INSIGHTS_ROLE = "read:insights"
+    READ_ALARMS_ROLE = "read:alarms"
+    READ_SERVICES_ROLE = "read:services"
+    WRITE_SERVICES_ROLE = "write:services"
+    WRITE_USER_ROLE = "write:user"
+    WRITE_ADMIN_ROLE = "write:admin"
+    WRITE_LOGS_ROLE = "write:logs"
+    WRITE_ASSETS_ROLE = "write:assets"
+    WRITE_ATTRIBUTES_ROLE = "write:attributes"
+    WRITE_RULES_ROLE = "write:rules"

src/service_ml_forecast/dependencies.py

@@ -21,13 +21,17 @@
 The injectors are used to inject the services into the FastAPI app, or other dependencies.
 """
 
+import logging
+
 from fastapi.security import OAuth2PasswordBearer
 
 from service_ml_forecast.clients.openremote.openremote_client import OpenRemoteClient
 from service_ml_forecast.config import ENV
 from service_ml_forecast.services.model_config_service import ModelConfigService
 from service_ml_forecast.services.openremote_service import OpenRemoteService
 
+logger = logging.getLogger(__name__)
+
 __openremote_client = OpenRemoteClient(
     openremote_url=ENV.ML_OR_URL,
     keycloak_url=ENV.ML_OR_KEYCLOAK_URL,
@@ -54,13 +58,36 @@ def get_openremote_service() -> OpenRemoteService:
     return __openremote_service
 
 
+def get_openremote_issuers() -> list[str] | None:
+    """Get valid issuers from OpenRemote realms.
+
+    Returns:
+        List of valid issuer URLs or None if realms cannot be retrieved.
+    """
+    try:
+        openremote_service = get_openremote_service()
+        realms = openremote_service.get_realms()
+
+        if realms is None:
+            return None
+
+        urls = []
+        for realm in realms:
+            urls.append(f"{ENV.ML_OR_URL}/auth/realms/{realm.name}")
+        return urls
+    except Exception as e:
+        logger.error(f"Error getting issuers from OpenRemote: {e}", exc_info=True)
+        return None
+
+
+# --- Constants ---
+OPENREMOTE_KC_RESOURCE = "openremote"
+
 # --- OAuth2 Scheme ---
 # This is used to allow authorization via the Docs and Redoc pages
-# Also allows us to extract the token easily from the Authorization header
-# Does not validate the token, this is done in the KeycloakMiddleware!
-__realm_name = "master"
-oauth2_scheme = OAuth2PasswordBearer(
-    tokenUrl=f"{ENV.ML_OR_KEYCLOAK_URL}/realms/{__realm_name}/protocol/openid-connect/token",
+# Does not validate the token, this should be done via a middleware or manually
+OAUTH2_SCHEME = OAuth2PasswordBearer(
+    tokenUrl=f"{ENV.ML_OR_KEYCLOAK_URL}/realms/master/protocol/openid-connect/token",
     scopes={"openid": "OpenID Connect", "profile": "User profile", "email": "User email"},
     description="Login into the OpenRemote Management -- Expected Client ID: 'openremote'",
     auto_error=False,

src/service_ml_forecast/main.py

@@ -28,18 +28,16 @@
 from service_ml_forecast.api import model_config_route, web_route
 from service_ml_forecast.api.route_exception_handlers import register_exception_handlers
 from service_ml_forecast.config import ENV
-from service_ml_forecast.dependencies import get_openremote_service
+from service_ml_forecast.dependencies import get_openremote_issuers, get_openremote_service
 from service_ml_forecast.logging_config import LOGGING_CONFIG
-from service_ml_forecast.middlewares.keycloak_middleware import KeycloakMiddleware
+from service_ml_forecast.middlewares.keycloak.middleware import KeycloakMiddleware
 from service_ml_forecast.services.model_scheduler import ModelScheduler
 
 # Load the logging configuration
 logging.config.dictConfig(LOGGING_CONFIG)
 
 logger = logging.getLogger(__name__)
 
-IS_DEV = ENV.is_development()
-
 
 # FastAPI Lifecycle, handles startup and shutdown tasks
 @asynccontextmanager
@@ -62,6 +60,7 @@ async def lifespan(_app: FastAPI) -> AsyncGenerator[None]:
     lifespan=lifespan,
 )
 
+
 # --- API Docs ---
 if not ENV.ML_API_PUBLISH_DOCS:
     app.docs_url = None
@@ -70,20 +69,17 @@ async def lifespan(_app: FastAPI) -> AsyncGenerator[None]:
 
 
 # --- Middlewares ---
-# Last in the chain -- GZIP
 app.add_middleware(GZipMiddleware, minimum_size=1000)
 
-# Second to last in the chain -- Keycloak
 if ENV.ML_API_MIDDLEWARE_KEYCLOAK:
     app.add_middleware(
         KeycloakMiddleware,
-        keycloak_url=ENV.ML_OR_KEYCLOAK_URL,
         excluded_routes=["/docs", "/redoc", "/openapi.json", "/ui"],
+        issuer_provider=get_openremote_issuers,
     )
 else:
     logger.warning("Keycloak middleware disabled! This is NOT recommended in production!")
 
-# First in the chain -- CORS
 app.add_middleware(
     CORSMiddleware,
     allow_origins=ENV.ML_WEBSERVER_ORIGINS,
@@ -111,6 +107,9 @@ def initialize_background_services() -> None:
 
 # Entrypoint for the service
 if __name__ == "__main__":
+    # Check if the application is running in development mode
+    IS_DEV = ENV.is_development()
+
     if IS_DEV:
         logger.warning("Application is running in development mode -- DO NOT USE IN PRODUCTION")
 

src/service_ml_forecast/middlewares/keycloak/__init__.py

@@ -0,0 +1,43 @@
+# Copyright 2025, OpenRemote Inc.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""
+Keycloak constants.
+
+These constants are used to configure the Keycloak middleware, decorators
+hold common error messages.
+"""
+
+# Constants for JWT and JWKS configuration
+JWKS_CACHE_TTL_SECONDS = 600  # 10 minutes
+JWKS_REQUEST_TIMEOUT_SECONDS = 10.0
+JWKS_ENDPOINT_PATH = "/protocol/openid-connect/certs"
+
+# JWT token constants
+JWT_ALGORITHM_RS256 = "RS256"
+JWT_KEY_TYPE_RSA = "RSA"
+JWT_KEY_USE_SIGNATURE = "sig"
+
+# Common error messages
+ERROR_MISSING_AUTH_HEADER = "Missing or malformed Authorization header"
+ERROR_INVALID_TOKEN = "Invalid token"
+ERROR_TOKEN_EXPIRED = "Token has expired"
+ERROR_INSUFFICIENT_PERMISSIONS = "Insufficient permissions"
+ERROR_REALM_REQUIRED = "Realm is required"
+ERROR_USER_NOT_AUTHENTICATED = "User not authenticated"
+ERROR_INTERNAL_SERVER_ERROR = "Internal server error"
+ERROR_UNEXPECTED_ERROR = "An unexpected error occurred"