fix(auth): allow unauthenticated access to health and version endpoints (#3736)

The AuthenticationMiddleware was blocking all requests without an
Authorization header, including health and version endpoints that are
needed by monitoring tools, load balancers, and Kubernetes probes.

This commit allows endpoints ending in /health or /version to bypass
authentication, enabling operational tooling to function properly
without requiring credentials.

Closes: #3735

Signed-off-by: Derek Higgins <derekh@redhat.com>

llama_stack/apis/inspect/inspect.py

@@ -73,7 +73,7 @@ class Inspect(Protocol):
         """
         ...
 
-    @webmethod(route="/health", method="GET", level=LLAMA_STACK_API_V1)
+    @webmethod(route="/health", method="GET", level=LLAMA_STACK_API_V1, require_authentication=False)
     async def health(self) -> HealthInfo:
         """Get health status.
 
@@ -83,7 +83,7 @@ class Inspect(Protocol):
         """
         ...
 
-    @webmethod(route="/version", method="GET", level=LLAMA_STACK_API_V1)
+    @webmethod(route="/version", method="GET", level=LLAMA_STACK_API_V1, require_authentication=False)
     async def version(self) -> VersionInfo:
         """Get version.
 

llama_stack/core/server/auth.py

@@ -27,6 +27,11 @@ class AuthenticationMiddleware:
     3. Extracts user attributes from the provider's response
     4. Makes these attributes available to the route handlers for access control
 
+    Unauthenticated Access:
+    Endpoints can opt out of authentication by setting require_authentication=False
+    in their @webmethod decorator. This is typically used for operational endpoints
+    like /health and /version to support monitoring, load balancers, and observability tools.
+
     The middleware supports multiple authentication providers through the AuthProvider interface:
     - Kubernetes: Validates tokens against the Kubernetes API server
     - Custom: Validates tokens against a custom endpoint
@@ -88,7 +93,26 @@ class AuthenticationMiddleware:
 
     async def __call__(self, scope, receive, send):
         if scope["type"] == "http":
-            # First, handle authentication
+            # Find the route and check if authentication is required
+            path = scope.get("path", "")
+            method = scope.get("method", hdrs.METH_GET)
+
+            if not hasattr(self, "route_impls"):
+                self.route_impls = initialize_route_impls(self.impls)
+
+            webmethod = None
+            try:
+                _, _, _, webmethod = find_matching_route(method, path, self.route_impls)
+            except ValueError:
+                # If no matching endpoint is found, pass here to run auth anyways
+                pass
+
+            # If webmethod explicitly sets require_authentication=False, allow without auth
+            if webmethod and webmethod.require_authentication is False:
+                logger.debug(f"Allowing unauthenticated access to endpoint: {path}")
+                return await self.app(scope, receive, send)
+
+            # Handle authentication
             headers = dict(scope.get("headers", []))
             auth_header = headers.get(b"authorization", b"").decode()
 
@@ -127,19 +151,7 @@ class AuthenticationMiddleware:
             )
 
             # Scope-based API access control
-            path = scope.get("path", "")
-            method = scope.get("method", hdrs.METH_GET)
-
-            if not hasattr(self, "route_impls"):
-                self.route_impls = initialize_route_impls(self.impls)
-
-            try:
-                _, _, _, webmethod = find_matching_route(method, path, self.route_impls)
-            except ValueError:
-                # If no matching endpoint is found, pass through to FastAPI
-                return await self.app(scope, receive, send)
-
-            if webmethod.required_scope:
+            if webmethod and webmethod.required_scope:
                 user = user_from_scope(scope)
                 if not _has_required_scope(webmethod.required_scope, user):
                     return await self._send_auth_error(

llama_stack/schema_utils.py

@@ -61,6 +61,7 @@ class WebMethod:
     descriptive_name: str | None = None
     required_scope: str | None = None
     deprecated: bool | None = False
+    require_authentication: bool | None = True
 
 
 CallableT = TypeVar("CallableT", bound=Callable[..., Any])
@@ -77,6 +78,7 @@ def webmethod(
     descriptive_name: str | None = None,
     required_scope: str | None = None,
     deprecated: bool | None = False,
+    require_authentication: bool | None = True,
 ) -> Callable[[CallableT], CallableT]:
     """
     Decorator that supplies additional metadata to an endpoint operation function.
@@ -86,6 +88,7 @@ def webmethod(
     :param request_examples: Sample requests that the operation might take. Pass a list of objects, not JSON.
     :param response_examples: Sample responses that the operation might produce. Pass a list of objects, not JSON.
     :param required_scope: Required scope for this endpoint (e.g., 'monitoring.viewer').
+    :param require_authentication: Whether this endpoint requires authentication (default True).
     """
 
     def wrap(func: CallableT) -> CallableT:
@@ -100,6 +103,7 @@ def webmethod(
             descriptive_name=descriptive_name,
             required_scope=required_scope,
             deprecated=deprecated,
+            require_authentication=require_authentication if require_authentication is not None else True,
         )
 
         # Store all webmethods in a list to support multiple decorators