Merge pull request #57 from luis5tb/max-scopes

luis5tb · web-flow · commit e2f1e942fb8c · 2026-03-26T15:24:57.000+01:00
feat: enforce OAuth scope allowlist on access tokens
diff --git a/.env.example b/.env.example
@@ -31,6 +31,10 @@ RED_HAT_SSO_CLIENT_SECRET=your_client_secret
 # Required scopes for token introspection (comma-separated, default: api.console,api.ocm)
 AGENT_REQUIRED_SCOPE=api.console,api.ocm
 
+# Allowed scopes allowlist (comma-separated, default: openid,profile,email,api.console,api.ocm)
+# Tokens carrying scopes outside this list are rejected (HTTP 403).
+AGENT_ALLOWED_SCOPES=openid,profile,email,api.console,api.ocm
+
 # -----------------------------------------------------------------------------
 # Red Hat Lightspeed MCP Server Configuration
 # -----------------------------------------------------------------------------
diff --git a/deploy/cloudrun/README.md b/deploy/cloudrun/README.md
@@ -667,6 +667,7 @@ Bearer token that is active and carries the `api.console` and `api.ocm` scopes.
 | `MARKETPLACE_HANDLER_URL` | URL of the marketplace-handler service. Used to build the DCR endpoints in the AgentCard. If empty, falls back to `AGENT_PROVIDER_URL`. Set automatically by `deploy.sh`. |
 | `AGENT_PROVIDER_ORGANIZATION_URL` | Provider's organization website URL (default: `https://www.redhat.com`). Used in AgentCard `provider.url` and as the expected JWT audience for Google DCR `software_statement` validation. Set in YAML configs, not changed by `deploy.sh`. |
 | `AGENT_REQUIRED_SCOPE` | Comma-separated OAuth scopes required in tokens (default: `api.console,api.ocm`) |
+| `AGENT_ALLOWED_SCOPES` | Comma-separated allowlist of permitted scopes (default: `openid,profile,email,api.console,api.ocm`). Tokens with scopes outside this list are rejected (403). |
 
 ### Development Mode
 
@@ -1128,6 +1129,24 @@ gcloud run services update ${SERVICE_NAME:-lightspeed-agent} \
 This setting is also configurable in `service.yaml` via the
 `AGENT_REQUIRED_SCOPE` environment variable.
 
+**"Token carries disallowed scope(s): ..."**
+
+The agent enforces a scope allowlist (`AGENT_ALLOWED_SCOPES`) to prevent tokens
+with elevated privileges from being forwarded to downstream services.  If the
+token carries scopes not in the allowlist, you will see a 403 error.
+
+Add the missing scope(s) to the allowlist:
+
+```bash
+gcloud run services update ${SERVICE_NAME:-lightspeed-agent} \
+  --region=$GOOGLE_CLOUD_LOCATION \
+  --project=$GOOGLE_CLOUD_PROJECT \
+  --update-env-vars="AGENT_ALLOWED_SCOPES=openid,profile,email,api.console,api.ocm,your.extra.scope"
+```
+
+This setting is also configurable in `service.yaml` via the
+`AGENT_ALLOWED_SCOPES` environment variable.
+
 **Empty response or connection refused**
 
 - Ensure the proxy is running in a separate terminal
diff --git a/deploy/cloudrun/service.yaml b/deploy/cloudrun/service.yaml
@@ -94,6 +94,10 @@ spec:
             # Set to empty string to disable scope checking.
             - name: AGENT_REQUIRED_SCOPE
               value: "api.console,api.ocm"
+            # Comma-separated allowlist of OAuth scopes permitted in access tokens.
+            # Tokens carrying scopes outside this list are rejected (HTTP 403).
+            - name: AGENT_ALLOWED_SCOPES
+              value: "openid,profile,email,api.console,api.ocm"
             # Ensure production environment do not skip JWT validation
             - name: SKIP_JWT_VALIDATION
               value: "false"
diff --git a/deploy/podman/lightspeed-agent-configmap.yaml b/deploy/podman/lightspeed-agent-configmap.yaml
@@ -16,6 +16,7 @@ data:
   # Red Hat SSO Configuration
   RED_HAT_SSO_ISSUER: "https://sso.redhat.com/auth/realms/redhat-external"
   AGENT_REQUIRED_SCOPE: "api.console,api.ocm"
+  AGENT_ALLOWED_SCOPES: "openid,profile,email,api.console,api.ocm"
 
   # MCP Server Configuration (for agent)
   MCP_TRANSPORT_MODE: "http"
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -130,7 +130,7 @@ The main AI agent FastAPI application, providing:
 Handles all authentication and authorization:
 
 - **Token Introspection**: Validates tokens via Keycloak introspection endpoint (RFC 7662)
-- **Scope Checking**: Checks for required `api.console` and `api.ocm` scopes
+- **Scope Checking**: Checks for required `api.console` and `api.ocm` scopes; rejects tokens carrying scopes outside the configured allowlist
 - **Bypass for Discovery**: `/.well-known/agent.json` is public per A2A spec
 
 ### Agent Core
@@ -336,7 +336,7 @@ src/lightspeed_agent/
 
 - A2A query endpoints require valid Bearer token from Red Hat SSO
 - Tokens validated via Keycloak introspection endpoint (RFC 7662)
-- Required `api.console` and `api.ocm` scopes checked; returns 403 if missing
+- Required `api.console` and `api.ocm` scopes checked; returns 403 if missing or if token carries disallowed scopes
 
 ### Public Endpoints
 
diff --git a/docs/authentication-flow.md b/docs/authentication-flow.md
@@ -496,6 +496,7 @@ Gemini Enterprise                  Lightspeed Agent                      Red Hat
      |                                    |                                       |
      |                                    |-- Verify "active" == true             |
      |                                    |-- Verify required scopes present      |
+     |                                    |-- Verify no disallowed scopes         |
      |                                    |                                       |
      |                                    |-- Resolve order:                      |
      |                                    |   azp (ge-client-id)                  |
@@ -584,6 +585,19 @@ Gemini Enterprise                  Lightspeed Agent                      Red Hat
      |                                    |                                       |
      |   --- OR ---                       |                                       |
      |                                    |                                       |
+     |                                    |<-- { "active": true,                  |
+     |                                    |      "scope": "openid api.console     |
+     |                                    |        api.ocm admin.super" } --------|
+     |                                    |   (disallowed scopes present)         |
+     |                                    |                                       |
+     |<-- 403 { code: -32003,             |                                       |
+     |   message: "Forbidden",            |                                       |
+     |   detail: "Token carries           |                                       |
+     |     disallowed scope(s):           |                                       |
+     |     admin.super" } ---------------|                                       |
+     |                                    |                                       |
+     |   --- OR ---                       |                                       |
+     |                                    |                                       |
      |                                    |-- Look up azp → order_id              |
      |                                    |   FAIL: client not in credentials DB  |
      |                                    |         or order not ACTIVE           |
@@ -602,6 +616,7 @@ Gemini Enterprise                  Lightspeed Agent                      Red Hat
 | Introspection endpoint returns non-200 | 401 | -32001 | `Introspection request failed (HTTP {status})` |
 | Network error calling introspection endpoint | 401 | -32001 | `HTTP error calling introspection endpoint: {error}` |
 | Token missing required scope(s) | 403 | -32003 | `Token is missing required scope(s): api.console, api.ocm` |
+| Token carries disallowed scope(s) | 403 | -32003 | `Token carries disallowed scope(s): <scope_name>` |
 | `azp` client ID not found in credentials DB | 403 | -32003 | `No active order found for this client` |
 | Order ID not found in entitlements DB | 403 | -32003 | `No active order found for this client` |
 | Order state is not `ACTIVE` | 403 | -32003 | `No active order found for this client` |
diff --git a/docs/authentication.md b/docs/authentication.md
@@ -196,6 +196,10 @@ mismatch issues when tokens are issued by DCR-created clients (each has its own
 5. **Check Scope**: Agent checks that the required scopes (`api.console` and
    `api.ocm`) are present in the token's `scope` field.  If any are missing,
    the agent returns **403 Forbidden**.
+6. **Check Allowed Scopes**: Agent checks that the token does not carry scopes
+   outside the configured allowlist (`AGENT_ALLOWED_SCOPES`).  If disallowed
+   scopes are present, the agent returns **403 Forbidden**.  This prevents
+   tokens with elevated privileges from being forwarded to downstream services.
 6. **Build User**: Agent maps the introspection response to an
    `AuthenticatedUser` for downstream use.
 
@@ -223,6 +227,19 @@ must be:
 The required scopes are configurable via `AGENT_REQUIRED_SCOPE` (comma-separated,
 default: `api.console,api.ocm`).
 
+### Allowed Scopes (Scope Allowlist)
+
+In addition to checking that required scopes are present, the agent enforces an
+**allowlist** of permitted scopes via `AGENT_ALLOWED_SCOPES` (comma-separated,
+default: `openid,profile,email,api.console,api.ocm`).  Tokens carrying scopes
+outside this list are rejected with **403 Forbidden**.
+
+This is a defense-in-depth measure: since the agent forwards the caller's JWT
+to the MCP sidecar and downstream APIs, restricting scopes prevents tokens with
+elevated privileges from being exercised against those services.
+
+All permitted scopes must be explicitly listed in `AGENT_ALLOWED_SCOPES`.
+
 ### Introspection Response Fields
 
 The agent extracts the following fields from the introspection response:
@@ -287,6 +304,10 @@ RED_HAT_SSO_CLIENT_SECRET=your-client-secret
 
 # Required scopes checked during token introspection (comma-separated, default: api.console,api.ocm)
 AGENT_REQUIRED_SCOPE=api.console,api.ocm
+
+# Allowed scopes allowlist (comma-separated, default: openid,profile,email,api.console,api.ocm)
+# Tokens carrying scopes outside this list are rejected (HTTP 403).
+AGENT_ALLOWED_SCOPES=openid,profile,email,api.console,api.ocm
 ```
 
 ### Registering an OAuth Client
@@ -517,6 +538,7 @@ pytest tests/test_auth.py --cov=lightspeed_agent.auth
 | 401 | Token not active | Introspection returned `active: false` (expired, revoked, or invalid) |
 | 401 | Introspection failed | HTTP error calling introspection endpoint |
 | 403 | Insufficient scope | Token is active but missing required scope(s) (`api.console`, `api.ocm`) |
+| 403 | Disallowed scope | Token carries scope(s) outside the configured allowlist (`AGENT_ALLOWED_SCOPES`) |
 
 ### Error Response Format
 
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -39,6 +39,7 @@ GOOGLE_CLOUD_LOCATION=us-central1
 | `RED_HAT_SSO_CLIENT_ID` | - | Resource Server client ID (used for token introspection) |
 | `RED_HAT_SSO_CLIENT_SECRET` | - | Resource Server client secret |
 | `AGENT_REQUIRED_SCOPE` | `api.console,api.ocm` | Comma-separated OAuth scopes required in access tokens |
+| `AGENT_ALLOWED_SCOPES` | `openid,profile,email,api.console,api.ocm` | Comma-separated allowlist of permitted scopes. Tokens with scopes outside this list are rejected (403). |
 
 **Example:**
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -131,6 +131,14 @@ echo $TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | jq .scope
 
 **Fix**: Ensure the `api.console` and `api.ocm` Client Scopes exist in Keycloak and are assigned to the client that issued the token.
 
+### Disallowed Scope (403 Forbidden)
+
+**Symptom**: `Token carries disallowed scope(s): <scope_name>`
+
+The token contains scopes outside the `AGENT_ALLOWED_SCOPES` allowlist.
+
+**Fix**: Either add the scope to `AGENT_ALLOWED_SCOPES` or request a token without the extra scopes. All permitted scopes must be explicitly listed.
+
 ### OAuth Callback Errors
 
 **Symptom**: Callback fails with error
diff --git a/src/lightspeed_agent/auth/__init__.py b/src/lightspeed_agent/auth/__init__.py
@@ -11,6 +11,7 @@
     require_scope,
 )
 from lightspeed_agent.auth.introspection import (
+    DisallowedScopeError,
     InsufficientScopeError,
     TokenIntrospector,
     TokenValidationError,
@@ -31,6 +32,7 @@
     "TokenIntrospector",
     "TokenValidationError",
     "InsufficientScopeError",
+    "DisallowedScopeError",
     "get_token_introspector",
     # Middleware
     "AuthenticationMiddleware",
diff --git a/src/lightspeed_agent/auth/dependencies.py b/src/lightspeed_agent/auth/dependencies.py
@@ -8,6 +8,7 @@
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
 from lightspeed_agent.auth.introspection import (
+    DisallowedScopeError,
     InsufficientScopeError,
     TokenIntrospector,
     TokenValidationError,
@@ -62,6 +63,12 @@ async def get_current_user(
             status_code=status.HTTP_403_FORBIDDEN,
             detail=str(e),
         ) from None
+    except DisallowedScopeError as e:
+        logger.warning("Disallowed scope: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=str(e),
+        ) from None
     except TokenValidationError as e:
         logger.warning("Token validation failed: %s", e)
         raise HTTPException(
diff --git a/src/lightspeed_agent/auth/introspection.py b/src/lightspeed_agent/auth/introspection.py
@@ -31,6 +31,10 @@ class InsufficientScopeError(Exception):
     """Raised when a token is valid but lacks the required scope (HTTP 403)."""
 
 
+class DisallowedScopeError(Exception):
+    """Raised when a token carries scopes outside the allowed set (HTTP 403)."""
+
+
 class TokenIntrospector:
     """Validate Bearer tokens via the Keycloak introspection endpoint.
 
@@ -46,6 +50,7 @@ def __init__(self, settings: Settings | None = None) -> None:
         self._client_id = self._settings.red_hat_sso_client_id
         self._client_secret = self._settings.red_hat_sso_client_secret
         self._required_scopes = self._settings.required_scopes_list
+        self._allowed_scopes = self._settings.allowed_scopes_list
 
     async def validate_token(self, token: str) -> AuthenticatedUser:
         """Validate a Bearer token via introspection.
@@ -77,6 +82,13 @@ async def validate_token(self, token: str) -> AuthenticatedUser:
                 f"Token is missing required scope(s): {', '.join(missing)}"
             )
 
+        # Check that token does not carry scopes beyond the allowlist
+        disallowed = [s for s in scopes if s not in self._allowed_scopes]
+        if disallowed:
+            raise DisallowedScopeError(
+                f"Token carries disallowed scope(s): {', '.join(disallowed)}"
+            )
+
         return self._to_user(data, scopes)
 
     # ------------------------------------------------------------------
diff --git a/src/lightspeed_agent/config/settings.py b/src/lightspeed_agent/config/settings.py
@@ -236,11 +236,25 @@ class Settings(BaseSettings):
         ),
     )
 
+    # Agent allowed scopes (comma-separated allowlist)
+    agent_allowed_scopes: str = Field(
+        default="openid,profile,email,api.console,api.ocm",
+        description=(
+            "Comma-separated allowlist of OAuth scopes permitted in access tokens."
+            " Tokens carrying scopes outside this list are rejected (HTTP 403)."
+        ),
+    )
+
     @property
     def required_scopes_list(self) -> list[str]:
         """Parse comma-separated agent_required_scope into a list."""
         return [s.strip() for s in self.agent_required_scope.split(",") if s.strip()]
 
+    @property
+    def allowed_scopes_list(self) -> list[str]:
+        """Parse comma-separated agent_allowed_scopes into a list."""
+        return [s.strip() for s in self.agent_allowed_scopes.split(",") if s.strip()]
+
     @property
     def keycloak_introspection_endpoint(self) -> str:
         """Get the Keycloak token introspection endpoint URL."""
diff --git a/tests/test_auth.py b/tests/test_auth.py
@@ -9,6 +9,7 @@
 
 from lightspeed_agent.auth import AuthenticatedUser
 from lightspeed_agent.auth.introspection import (
+    DisallowedScopeError,
     InsufficientScopeError,
     TokenIntrospector,
     TokenValidationError,
@@ -194,6 +195,50 @@ async def test_dev_mode_returns_dev_user(self, dev_introspector):
         assert "api.console" in user.scopes
         assert "api.ocm" in user.scopes
 
+    @pytest.mark.asyncio
+    async def test_disallowed_scope_rejected(self, introspector):
+        """Test that a token with scopes outside the allowlist raises DisallowedScopeError."""
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "active": True,
+            "sub": "user-123",
+            "scope": "openid api.console api.ocm admin.superpower",
+            "exp": int(time.time()) + 3600,
+        }
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.return_value = mock_response
+            mock_instance.__aenter__.return_value = mock_instance
+            mock_instance.__aexit__.return_value = None
+            mock_client.return_value = mock_instance
+
+            with pytest.raises(DisallowedScopeError, match="admin.superpower"):
+                await introspector.validate_token("extra-scope-token")
+
+    @pytest.mark.asyncio
+    async def test_all_allowed_scopes_accepted(self, introspector):
+        """Test that a token with only allowed scopes passes validation."""
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "active": True,
+            "sub": "user-123",
+            "scope": "openid profile email api.console api.ocm",
+            "exp": int(time.time()) + 3600,
+        }
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.return_value = mock_response
+            mock_instance.__aenter__.return_value = mock_instance
+            mock_instance.__aexit__.return_value = None
+            mock_client.return_value = mock_instance
+
+            user = await introspector.validate_token("good-token")
+            assert set(user.scopes) == {"openid", "profile", "email", "api.console", "api.ocm"}
+
     @pytest.mark.asyncio
     async def test_azp_preferred_over_client_id(self, introspector):
         """Test that azp is used over client_id when both are present."""
