Role-based authorization layer

This commit adds a second authorization layer that evaluates what
authenticated users are allowed to do, separate from whether they can
authenticate at all. The authorization system sits between endpoint
handlers and the existing auth dependency injection.

# Architecture

The system uses two resolver interfaces that can be swapped based on
auth module (although `AccessResolver` shouldn't change much across
different auth modules):

- `RolesResolver`: given an `AuthTuple`, determine what roles the user has
- `AccessResolver`: given roles and an action, determine if access is allowed

For JWT auth, roles are extracted by applying user-provided rules
containing JSONPath expressions to JWT claims . Each role rule specifies
a JSONPath, operator (equals/contains/in), a value, and the resulting
roles to apply if the rule matches the user claims.

This lets you map claim values like `department: "engineering"` to roles
like "developer". Roles are arbitrary except for the special `*` role
which applies to everyone automatically.

Access rules then map roles to permitted actions.

# Implementation

The `@authorize(action)` decorator wraps endpoint functions and performs the check:

1. Extract `AuthTuple` from endpoint dependencies
2. Resolve user roles from auth credentials using the `RolesResolver`
3. Check if those roles permit the requested action using the
   `AccessResolver`
4. Raise 403 if denied, continue if allowed

All endpoints now declare what action they perform
(`READ_CONVERSATIONS`, `FEEDBACK`, etc.) through the `@authorize`
decorator. The middleware automatically handles the permission check
before the endpoint runs.

The middleware also populates the `request: Request` `state` property
with the `authorized_actions` set, which contains all actions the user
is allowed to perform based on their roles. Endpoints can then inspect
this property to dynamically adjust their behavior based on what the
user is allowed to do, for special actions such as listing others'
conversations (as opposed to listing only the user's own conversations)
or deleting conversations. These behaviors which are more "complicated"
than just whether the endpoint is accessible or not, as they depend on
the actual endpoint logic.

# Backwards compatibility

For non-JWT auth modules, we will default to no-op resolvers that allow
all access, maintaining current behavior.

# Technical notes

- All endpoints should accept `auth: Any =
  Depends(get_auth_dependency())` to use the authorization system. The
  parameter must be named `auth` to be recognized by the middleware.

# Config

Example configuration:

```yaml
      authentication:
        module: jwk-token
        jwk_config:
          url: ${SSO_BASE_URL}/protocol/openid-connect/certs
          jwt_configuration:
            user_id_claim: ${USER_ID_CLAIM}
            username_claim: ${USERNAME_CLAIM}
            role_rules:
              - jsonpath: "$.realm_access.roles[*]"
                operator: "contains"
                value: "redhat:employees"
                roles: ["redhat_employee"]
              - jsonpath: "$.realm_access.roles[*]"
                operator: "contains"
                value: "candlepin_system_access_view_edit_all"
                roles: ["read_only_admin"]
      authorization:
        access_rules:
          - role: "admin"
            actions:
            - query_other_conversations
            - delete_other_conversations
          - role: "read_only_admin"
            actions:
            - list_other_conversations
            - read_other_conversations
          - role: "redhat_employee"
            actions:
            - get_models
            - get_config
          - role: "*"
            actions:
            - query
            - streaming_query
            - get_conversation
            - list_conversations
            - delete_conversation
            - feedback
            - get_metrics
            - info
```

Author: omertuc

pyproject.toml

@@ -37,6 +37,7 @@ dependencies = [
     "openai==1.99.9",
     "sqlalchemy>=2.0.42",
     "semver<4.0.0",
+    "jsonpath-ng>=1.6.1",
 ]
 
 

src/app/endpoints/authorized.py

@@ -1,10 +1,11 @@
 """Handler for REST API call to authorized endpoint."""
 
 import logging
-from typing import Any
+from typing import Annotated, Any
 
 from fastapi import APIRouter, Depends
 
+from auth.interface import AuthTuple
 from auth import get_auth_dependency
 from models.responses import AuthorizedResponse, UnauthorizedResponse, ForbiddenResponse
 
@@ -31,7 +32,7 @@
 
 @router.post("/authorized", responses=authorized_responses)
 async def authorized_endpoint_handler(
-    auth: Any = Depends(auth_dependency),
+    auth: Annotated[AuthTuple, Depends(auth_dependency)],
 ) -> AuthorizedResponse:
     """
     Handle request to the /authorized endpoint.

src/app/endpoints/config.py

@@ -1,17 +1,22 @@
 """Handler for REST API call to retrieve service configuration."""
 
 import logging
-from typing import Any
+from typing import Annotated, Any
 
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Depends
 
-from models.config import Configuration
+from auth.interface import AuthTuple
+from auth import get_auth_dependency
+from authorization.middleware import authorize
 from configuration import configuration
+from models.config import Action, Configuration
 from utils.endpoints import check_configuration_loaded
 
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["config"])
 
+auth_dependency = get_auth_dependency()
+
 
 get_config_responses: dict[int | str, dict[str, Any]] = {
     200: {
@@ -56,7 +61,11 @@
 
 
 @router.get("/config", responses=get_config_responses)
-def config_endpoint_handler(_request: Request) -> Configuration:
+@authorize(Action.GET_CONFIG)
+async def config_endpoint_handler(
+    auth: Annotated[AuthTuple, Depends(auth_dependency)],
+    request: Request,
+) -> Configuration:
     """
     Handle requests to the /config endpoint.
 
@@ -66,6 +75,12 @@ def config_endpoint_handler(_request: Request) -> Configuration:
     Returns:
         Configuration: The loaded service configuration object.
     """
+    # Used only for authorization
+    _ = auth
+
+    # Nothing interesting in the request
+    _ = request
+
     # ensure that configuration is loaded
     check_configuration_loaded(configuration)
 

src/app/endpoints/conversations.py

@@ -5,19 +5,21 @@
 
 from llama_stack_client import APIConnectionError, NotFoundError
 
-from fastapi import APIRouter, HTTPException, status, Depends
+from fastapi import APIRouter, HTTPException, Request, status, Depends
 
 from client import AsyncLlamaStackClientHolder
 from configuration import configuration
+from app.database import get_session
+from auth import get_auth_dependency
+from authorization.middleware import authorize
+from models.config import Action
+from models.database.conversations import UserConversation
 from models.responses import (
     ConversationResponse,
     ConversationDeleteResponse,
     ConversationsListResponse,
     ConversationDetails,
 )
-from models.database.conversations import UserConversation
-from auth import get_auth_dependency
-from app.database import get_session
 from utils.endpoints import check_configuration_loaded, validate_conversation_ownership
 from utils.suid import check_suid
 
@@ -146,7 +148,9 @@ def simplify_session_data(session_data: dict) -> list[dict[str, Any]]:
 
 
 @router.get("/conversations", responses=conversations_list_responses)
-def get_conversations_list_endpoint_handler(
+@authorize(Action.LIST_CONVERSATIONS)
+async def get_conversations_list_endpoint_handler(
+    request: Request,
     auth: Any = Depends(auth_dependency),
 ) -> ConversationsListResponse:
     """Handle request to retrieve all conversations for the authenticated user."""
@@ -158,11 +162,16 @@ def get_conversations_list_endpoint_handler(
 
     with get_session() as session:
         try:
-            # Get all conversations for this user
-            user_conversations = (
-                session.query(UserConversation).filter_by(user_id=user_id).all()
+            query = session.query(UserConversation)
+
+            filtered_query = (
+                query
+                if Action.LIST_OTHERS_CONVERSATIONS in request.state.authorized_actions
+                else query.filter_by(user_id=user_id)
             )
 
+            user_conversations = filtered_query.all()
+
             # Return conversation summaries with metadata
             conversations = [
                 ConversationDetails(
@@ -200,7 +209,9 @@ def get_conversations_list_endpoint_handler(
 
 
 @router.get("/conversations/{conversation_id}", responses=conversation_responses)
+@authorize(Action.GET_CONVERSATION)
 async def get_conversation_endpoint_handler(
+    request: Request,
     conversation_id: str,
     auth: Any = Depends(auth_dependency),
 ) -> ConversationResponse:
@@ -239,6 +250,9 @@ async def get_conversation_endpoint_handler(
     validate_conversation_ownership(
         user_id=user_id,
         conversation_id=conversation_id,
+        others_allowed=(
+            Action.READ_OTHERS_CONVERSATIONS in request.state.authorized_actions
+        ),
     )
 
     agent_id = conversation_id
@@ -309,7 +323,9 @@ async def get_conversation_endpoint_handler(
 @router.delete(
     "/conversations/{conversation_id}", responses=conversation_delete_responses
 )
+@authorize(Action.DELETE_CONVERSATION)
 async def delete_conversation_endpoint_handler(
+    request: Request,
     conversation_id: str,
     auth: Any = Depends(auth_dependency),
 ) -> ConversationDeleteResponse:
@@ -342,6 +358,9 @@ async def delete_conversation_endpoint_handler(
     validate_conversation_ownership(
         user_id=user_id,
         conversation_id=conversation_id,
+        others_allowed=(
+            Action.DELETE_OTHERS_CONVERSATIONS in request.state.authorized_actions
+        ),
     )
 
     agent_id = conversation_id

src/app/endpoints/feedback.py

@@ -5,19 +5,21 @@
 from pathlib import Path
 import json
 from datetime import datetime, UTC
-from fastapi import APIRouter, Request, HTTPException, Depends, status
+from fastapi import APIRouter, HTTPException, Depends, Request, status
 
 from auth import get_auth_dependency
 from auth.interface import AuthTuple
+from authorization.middleware import authorize
 from configuration import configuration
+from models.config import Action
+from models.requests import FeedbackRequest
 from models.responses import (
     ErrorResponse,
     FeedbackResponse,
     StatusResponse,
     UnauthorizedResponse,
     ForbiddenResponse,
 )
-from models.requests import FeedbackRequest
 from utils.suid import get_suid
 
 logger = logging.getLogger(__name__)
@@ -79,7 +81,8 @@ async def assert_feedback_enabled(_request: Request) -> None:
 
 
 @router.post("", responses=feedback_response)
-def feedback_endpoint_handler(
+@authorize(Action.FEEDBACK)
+async def feedback_endpoint_handler(
     feedback_request: FeedbackRequest,
     auth: Annotated[AuthTuple, Depends(auth_dependency)],
     _ensure_feedback_enabled: Any = Depends(assert_feedback_enabled),

src/app/endpoints/health.py

@@ -6,12 +6,16 @@
 """
 
 import logging
-from typing import Any
+from typing import Annotated, Any
 
 from llama_stack.providers.datatypes import HealthStatus
 
-from fastapi import APIRouter, status, Response
+from fastapi import APIRouter, status, Response, Depends
 from client import AsyncLlamaStackClientHolder
+from auth.interface import AuthTuple
+from auth import get_auth_dependency
+from authorization.middleware import authorize
+from models.config import Action
 from models.responses import (
     LivenessResponse,
     ReadinessResponse,
@@ -21,6 +25,8 @@
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["health"])
 
+auth_dependency = get_auth_dependency()
+
 
 async def get_providers_health_statuses() -> list[ProviderHealthStatus]:
     """
@@ -72,14 +78,21 @@ async def get_providers_health_statuses() -> list[ProviderHealthStatus]:
 
 
 @router.get("/readiness", responses=get_readiness_responses)
-async def readiness_probe_get_method(response: Response) -> ReadinessResponse:
+@authorize(Action.INFO)
+async def readiness_probe_get_method(
+    auth: Annotated[AuthTuple, Depends(auth_dependency)],
+    response: Response,
+) -> ReadinessResponse:
     """
     Handle the readiness probe endpoint, returning service readiness.
 
     If any provider reports an error status, responds with HTTP 503
     and details of unhealthy providers; otherwise, indicates the
     service is ready.
     """
+    # Used only for authorization
+    _ = auth
+
     provider_statuses = await get_providers_health_statuses()
 
     # Check if any provider is unhealthy (not counting not_implemented as unhealthy)
@@ -112,11 +125,17 @@ async def readiness_probe_get_method(response: Response) -> ReadinessResponse:
 
 
 @router.get("/liveness", responses=get_liveness_responses)
-def liveness_probe_get_method() -> LivenessResponse:
+@authorize(Action.INFO)
+async def liveness_probe_get_method(
+    auth: Annotated[AuthTuple, Depends(auth_dependency)],
+) -> LivenessResponse:
     """
     Return the liveness status of the service.
 
     Returns:
         LivenessResponse: Indicates that the service is alive.
     """
+    # Used only for authorization
+    _ = auth
+
     return LivenessResponse(alive=True)

src/app/endpoints/info.py

@@ -1,17 +1,24 @@
 """Handler for REST API call to provide info."""
 
 import logging
-from typing import Any
+from typing import Annotated, Any
 
 from fastapi import APIRouter, Request
+from fastapi import Depends
 
+from auth.interface import AuthTuple
+from auth import get_auth_dependency
+from authorization.middleware import authorize
 from configuration import configuration
-from version import __version__
+from models.config import Action
 from models.responses import InfoResponse
+from version import __version__
 
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["info"])
 
+auth_dependency = get_auth_dependency()
+
 
 get_info_responses: dict[int | str, dict[str, Any]] = {
     200: {
@@ -22,7 +29,11 @@
 
 
 @router.get("/info", responses=get_info_responses)
-def info_endpoint_handler(_request: Request) -> InfoResponse:
+@authorize(Action.INFO)
+async def info_endpoint_handler(
+    auth: Annotated[AuthTuple, Depends(auth_dependency)],
+    request: Request,
+) -> InfoResponse:
     """
     Handle request to the /info endpoint.
 
@@ -32,4 +43,10 @@ def info_endpoint_handler(_request: Request) -> InfoResponse:
     Returns:
         InfoResponse: An object containing the service's name and version.
     """
+    # Used only for authorization
+    _ = auth
+
+    # Nothing interesting in the request
+    _ = request
+
     return InfoResponse(name=configuration.configuration.name, version=__version__)

src/app/endpoints/metrics.py

@@ -1,19 +1,30 @@
 """Handler for REST API call to provide metrics."""
 
+from typing import Annotated
 from fastapi.responses import PlainTextResponse
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Depends
 from prometheus_client import (
     generate_latest,
     CONTENT_TYPE_LATEST,
 )
 
+from auth.interface import AuthTuple
+from auth import get_auth_dependency
+from authorization.middleware import authorize
+from models.config import Action
 from metrics.utils import setup_model_metrics
 
 router = APIRouter(tags=["metrics"])
 
+auth_dependency = get_auth_dependency()
+
 
 @router.get("/metrics", response_class=PlainTextResponse)
-async def metrics_endpoint_handler(_request: Request) -> PlainTextResponse:
+@authorize(Action.GET_METRICS)
+async def metrics_endpoint_handler(
+    auth: Annotated[AuthTuple, Depends(auth_dependency)],
+    request: Request,
+) -> PlainTextResponse:
     """
     Handle request to the /metrics endpoint.
 
@@ -24,6 +35,12 @@ async def metrics_endpoint_handler(_request: Request) -> PlainTextResponse:
     set up, then responds with the current metrics snapshot in
     Prometheus format.
     """
+    # Used only for authorization
+    _ = auth
+
+    # Nothing interesting in the request
+    _ = request
+
     # Setup the model metrics if not already done. This is a one-time setup
     # and will not be run again on subsequent calls to this endpoint
     await setup_model_metrics()