fix: Remove unused scope-based endpoint authorization feature (llamastack#4734)

The scope-based authorization feature was only used by the telemetry API
endpoints which were removed in commit 866c13c. Since no endpoints
currently use this feature, remove it entirely.

Changes:
o Remove required_scope parameter from WebMethod dataclass and webmethod
decorator o Remove scope checking logic from AuthenticationMiddleware o
Remove _has_required_scope helper function
o Remove scope authorization documentation
o Remove scope-related tests and fixtures

--
This code is unused since
llamastack#3740

Author: derekhiggins

docs/docs/distributions/configuration.mdx

@@ -794,36 +794,6 @@ For a request to succeed:
 2. User must pass resource authorization (can read `model::llama-3-2-3b`)
 3. Both checks must pass
 
-#### API Endpoint Authorization with Scopes
-
-In addition to resource-based access control, Llama Stack supports endpoint-level authorization using OAuth 2.0 style scopes. When authentication is enabled, specific API endpoints require users to have particular scopes in their authentication token.
-
-**Authentication Configuration:**
-
-For **JWT/OAuth2 providers**, scopes should be included in the JWT's claims:
-```json
-{
-  "sub": "user123",
-  "scope": "<scope>",
-  "aud": "llama-stack"
-}
-```
-
-For **custom authentication providers**, the endpoint must return user attributes including the `scopes` array:
-```json
-{
-  "principal": "user123",
-  "attributes": {
-    "scopes": ["<scope>"]
-  }
-}
-```
-
-**Behavior:**
-- Users without the required scope receive a 403 Forbidden response
-- When authentication is disabled, scope checks are bypassed
-- Endpoints without `required_scope` work normally for all authenticated users
-
 ### Quota Configuration
 
 The `quota` section allows you to enable server-side request throttling for both

src/llama_stack/core/server/auth.py

@@ -154,16 +154,6 @@ async def __call__(self, scope, receive, send):
                 f"Authentication successful: {validation_result.principal} with {len(validation_result.attributes)} attributes"
             )
 
-            # Scope-based API access control
-            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(
-                        send,
-                        f"Access denied: user does not have required scope: {webmethod.required_scope}",
-                        status=403,
-                    )
-
         return await self.app(scope, receive, send)
 
     async def _send_auth_error(self, send, message, status=401):
@@ -179,18 +169,6 @@ async def _send_auth_error(self, send, message, status=401):
         await send({"type": "http.response.body", "body": error_msg})
 
 
-def _has_required_scope(required_scope: str, user: User | None) -> bool:
-    # if no user, assume auth is not enabled
-    if not user:
-        return True
-
-    if not user.attributes:
-        return False
-
-    user_scopes = user.attributes.get("scopes", [])
-    return required_scope in user_scopes
-
-
 class RouteAuthorizationMiddleware:
     """Middleware that enforces route-level access control.
 

src/llama_stack_api/schema_utils.py

@@ -149,7 +149,6 @@ class WebMethod:
     raw_bytes_request_body: bool | None = False
     # A descriptive name of the corresponding span created by tracing
     descriptive_name: str | None = None
-    required_scope: str | None = None
     deprecated: bool | None = False
     require_authentication: bool | None = True
 
@@ -166,7 +165,6 @@ def webmethod(
     response_examples: list[Any] | None = None,
     raw_bytes_request_body: bool | None = False,
     descriptive_name: str | None = None,
-    required_scope: str | None = None,
     deprecated: bool | None = False,
     require_authentication: bool | None = True,
 ) -> Callable[[CallableT], CallableT]:
@@ -177,7 +175,6 @@ def webmethod(
     :param public: True if the operation can be invoked without prior authentication.
     :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).
     """
 
@@ -191,7 +188,6 @@ def wrap(func: CallableT) -> CallableT:
             response_examples=response_examples,
             raw_bytes_request_body=raw_bytes_request_body,
             descriptive_name=descriptive_name,
-            required_scope=required_scope,
             deprecated=deprecated,
             require_authentication=require_authentication if require_authentication is not None else True,
         )

tests/unit/server/test_auth.py

@@ -21,8 +21,7 @@
     OAuth2JWKSConfig,
     OAuth2TokenAuthConfig,
 )
-from llama_stack.core.request_headers import User
-from llama_stack.core.server.auth import AuthenticationMiddleware, _has_required_scope
+from llama_stack.core.server.auth import AuthenticationMiddleware
 from llama_stack.core.server.auth_providers import (
     get_attributes_from_claims,
 )
@@ -143,11 +142,10 @@ def middleware_with_mocks(mock_auth_endpoint):
     )
     middleware = AuthenticationMiddleware(mock_app, auth_config, {})
 
-    # Mock the route_impls to simulate finding routes with required scopes
     from llama_stack_api import WebMethod
 
     routes = {
-        ("POST", "/test/scoped"): WebMethod(route="/test/scoped", method="POST", required_scope="test.read"),
+        ("POST", "/test/scoped"): WebMethod(route="/test/scoped", method="POST"),
         ("GET", "/test/public"): WebMethod(route="/test/public", method="GET"),
         ("GET", "/health"): WebMethod(route="/health", method="GET", require_authentication=False),
         ("GET", "/version"): WebMethod(route="/version", method="GET", require_authentication=False),
@@ -193,36 +191,6 @@ async def mock_post_exception(*args, **kwargs):
     raise Exception("Connection error")
 
 
-async def mock_post_success_with_scope(*args, **kwargs):
-    """Mock auth response for user with test.read scope"""
-    return MockResponse(
-        200,
-        {
-            "message": "Authentication successful",
-            "principal": "test-user",
-            "attributes": {
-                "scopes": ["test.read", "other.scope"],
-                "roles": ["user"],
-            },
-        },
-    )
-
-
-async def mock_post_success_no_scope(*args, **kwargs):
-    """Mock auth response for user without required scope"""
-    return MockResponse(
-        200,
-        {
-            "message": "Authentication successful",
-            "principal": "test-user",
-            "attributes": {
-                "scopes": ["other.scope"],
-                "roles": ["user"],
-            },
-        },
-    )
-
-
 # HTTP Endpoint Tests
 def test_missing_auth_header(http_client):
     response = http_client.get("/test")
@@ -781,125 +749,6 @@ def test_valid_introspection_with_custom_mapping_authentication(
     assert response.json() == {"message": "Authentication successful"}
 
 
-# Scope-based authorization tests
-@patch("httpx.AsyncClient.post", new=mock_post_success_with_scope)
-async def test_scope_authorization_success(middleware_with_mocks, valid_api_key):
-    """Test that user with required scope can access protected endpoint"""
-    middleware, mock_app = middleware_with_mocks
-    mock_receive = AsyncMock()
-    mock_send = AsyncMock()
-
-    scope = {
-        "type": "http",
-        "path": "/test/scoped",
-        "method": "POST",
-        "headers": [(b"authorization", f"Bearer {valid_api_key}".encode())],
-    }
-
-    await middleware(scope, mock_receive, mock_send)
-
-    # Should call the downstream app (no 403 error sent)
-    mock_app.assert_called_once_with(scope, mock_receive, mock_send)
-    mock_send.assert_not_called()
-
-
-@patch("httpx.AsyncClient.post", new=mock_post_success_no_scope)
-async def test_scope_authorization_denied(middleware_with_mocks, valid_api_key):
-    """Test that user without required scope gets 403 access denied"""
-    middleware, mock_app = middleware_with_mocks
-    mock_receive = AsyncMock()
-    mock_send = AsyncMock()
-
-    scope = {
-        "type": "http",
-        "path": "/test/scoped",
-        "method": "POST",
-        "headers": [(b"authorization", f"Bearer {valid_api_key}".encode())],
-    }
-
-    await middleware(scope, mock_receive, mock_send)
-
-    # Should send 403 error, not call downstream app
-    mock_app.assert_not_called()
-    assert mock_send.call_count == 2  # start + body
-
-    # Check the response
-    start_call = mock_send.call_args_list[0][0][0]
-    assert start_call["status"] == 403
-
-    body_call = mock_send.call_args_list[1][0][0]
-    body_text = body_call["body"].decode()
-    assert "Access denied" in body_text
-    assert "test.read" in body_text
-
-
-@patch("httpx.AsyncClient.post", new=mock_post_success_no_scope)
-async def test_public_endpoint_no_scope_required(middleware_with_mocks, valid_api_key):
-    """Test that public endpoints work without specific scopes"""
-    middleware, mock_app = middleware_with_mocks
-    mock_receive = AsyncMock()
-    mock_send = AsyncMock()
-
-    scope = {
-        "type": "http",
-        "path": "/test/public",
-        "method": "GET",
-        "headers": [(b"authorization", f"Bearer {valid_api_key}".encode())],
-    }
-
-    await middleware(scope, mock_receive, mock_send)
-
-    # Should call the downstream app (no error)
-    mock_app.assert_called_once_with(scope, mock_receive, mock_send)
-    mock_send.assert_not_called()
-
-
-async def test_scope_authorization_no_auth_disabled(middleware_with_mocks):
-    """Test that when auth is disabled (no user), scope checks are bypassed"""
-    middleware, mock_app = middleware_with_mocks
-    mock_receive = AsyncMock()
-    mock_send = AsyncMock()
-
-    scope = {
-        "type": "http",
-        "path": "/test/scoped",
-        "method": "POST",
-        "headers": [],  # No authorization header
-    }
-
-    await middleware(scope, mock_receive, mock_send)
-
-    # Should send 401 auth error, not call downstream app
-    mock_app.assert_not_called()
-    assert mock_send.call_count == 2  # start + body
-
-    # Check the response
-    start_call = mock_send.call_args_list[0][0][0]
-    assert start_call["status"] == 401
-
-    body_call = mock_send.call_args_list[1][0][0]
-    body_text = body_call["body"].decode()
-    assert "Authentication required" in body_text
-
-
-def test_has_required_scope_function():
-    """Test the _has_required_scope function directly"""
-    # Test user with required scope
-    user_with_scope = User(principal="test-user", attributes={"scopes": ["test.read", "other.scope"]})
-    assert _has_required_scope("test.read", user_with_scope)
-
-    # Test user without required scope
-    user_without_scope = User(principal="test-user", attributes={"scopes": ["other.scope"]})
-    assert not _has_required_scope("test.read", user_without_scope)
-
-    # Test user with no scopes attribute
-    user_no_scopes = User(principal="test-user", attributes={})
-    assert not _has_required_scope("test.read", user_no_scopes)
-
-    # Test no user (auth disabled)
-    assert _has_required_scope("test.read", None)
-
-
 @pytest.fixture
 def mock_kubernetes_api_server():
     return "https://api.cluster.example.com:6443"