Merge pull request #51 from luis5tb/scopes

feat: replace agent:insights scope with api.console and api.ocm

Author: luis5tb

.env.example

@@ -28,8 +28,8 @@ RED_HAT_SSO_ISSUER=https://sso.redhat.com/auth/realms/redhat-external
 RED_HAT_SSO_CLIENT_ID=your_client_id
 RED_HAT_SSO_CLIENT_SECRET=your_client_secret
 
-# Required scope for token introspection (default: agent:insights)
-AGENT_REQUIRED_SCOPE=agent:insights
+# Required scopes for token introspection (comma-separated, default: api.console,api.ocm)
+AGENT_REQUIRED_SCOPE=api.console,api.ocm
 
 # -----------------------------------------------------------------------------
 # Red Hat Lightspeed MCP Server Configuration

deploy/cloudrun/README.md

@@ -614,7 +614,7 @@ Client                     Agent                   MCP Server        console.red
 
 The agent uses **Red Hat SSO** (Keycloak) for authentication via **token
 introspection** (RFC 7662).  Requests to the A2A endpoint (POST /) require a
-Bearer token that is active and carries the `agent:insights` scope.
+Bearer token that is active and carries the `api.console` and `api.ocm` scopes.
 
 ### Authentication Flow
 
@@ -637,7 +637,7 @@ Bearer token that is active and carries the `agent:insights` scope.
      │    Bearer token │                    │                   │                     │
      ├────────────────►│ 4. Introspect      │                   │                     │
      │                 │    token + check   │                   │                     │
-     │                 │    agent:insights  │                   │                     │
+     │                 │    required scopes │                   │                     │
      │                 ├───────────────────►│                   │                     │
      │                 │                    │                   │                     │
      │                 │ 5. MCP tool call   │                   │                     │
@@ -666,7 +666,7 @@ Bearer token that is active and carries the `agent:insights` scope.
 | `redhat-sso-client-secret` | Resource Server client secret |
 | `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` | OAuth scope required in tokens (default: `agent:insights`) |
+| `AGENT_REQUIRED_SCOPE` | Comma-separated OAuth scopes required in tokens (default: `api.console,api.ocm`) |
 
 ### Development Mode
 
@@ -1096,14 +1096,14 @@ The A2A protocol requires specific fields. A common mistake is omitting
 }
 ```
 
-**"Token is missing required scope: agent:insights"**
+**"Token is missing required scope(s): api.console, api.ocm"**
 
-The agent requires the `agent:insights` scope in the access token by
-default. If your Red Hat SSO client is not configured to issue this scope,
+The agent requires the `api.console` and `api.ocm` scopes in the access token
+by default. If your Red Hat SSO client is not configured to issue these scopes,
 you will see:
 
 ```json
-{"jsonrpc":"2.0","error":{"code":-32003,"message":"Forbidden","data":{"detail":"Token is missing required scope: agent:insights"}},"id":null}
+{"jsonrpc":"2.0","error":{"code":-32003,"message":"Forbidden","data":{"detail":"Token is missing required scope(s): api.console, api.ocm"}},"id":null}
 ```
 
 To temporarily disable the scope check for testing, set `AGENT_REQUIRED_SCOPE`
@@ -1122,7 +1122,7 @@ To restore the scope requirement:
 gcloud run services update ${SERVICE_NAME:-lightspeed-agent} \
   --region=$GOOGLE_CLOUD_LOCATION \
   --project=$GOOGLE_CLOUD_PROJECT \
-  --update-env-vars="AGENT_REQUIRED_SCOPE=agent:insights"
+  --update-env-vars="AGENT_REQUIRED_SCOPE=api.console,api.ocm"
 ```
 
 This setting is also configurable in `service.yaml` via the
@@ -1406,13 +1406,13 @@ IAT=$(curl -s -X POST \
 echo "Initial Access Token: $IAT"
 ```
 
-#### 5. Create the `agent:insights` Scope and Resource Server Client
+#### 5. Create the `api.console` and `api.ocm` Scopes and Resource Server Client
 
-The agent validates tokens via introspection and checks for the `agent:insights`
-scope.  The scope must exist in the realm **before** DCR creates clients that
-reference it.
+The agent validates tokens via introspection and checks for the `api.console`
+and `api.ocm` scopes.  The scopes must exist in the realm **before** DCR
+creates clients that reference them.
 
-**Create the `agent:insights` client scope:**
+**Create the `api.console` and `api.ocm` client scopes:**
 
 ```bash
 # Get a fresh admin token (the one from step 4 expires after 60s)
@@ -1429,23 +1429,33 @@ curl -s -X POST "$KEYCLOAK_URL/admin/realms/test-realm/client-scopes" \
   -H "Authorization: Bearer $ADMIN_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-    "name": "agent:insights",
+    "name": "api.console",
     "protocol": "openid-connect",
     "attributes": {"include.in.token.scope": "true"}
   }'
 
-# Allow agent:insights in the DCR client registration policy.
+# Create the api.ocm scope
+curl -s -X POST "$KEYCLOAK_URL/admin/realms/test-realm/client-scopes" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "api.ocm",
+    "protocol": "openid-connect",
+    "attributes": {"include.in.token.scope": "true"}
+  }'
+
+# Allow api.console and api.ocm in the DCR client registration policy.
 # Keycloak restricts which scopes can be requested during DCR.
 # Get the "authenticated" Allowed Client Scopes policy and add
-# agent:insights to it.
+# api.console and api.ocm to it.
 POLICY=$(curl -s \
   "$KEYCLOAK_URL/admin/realms/test-realm/components?type=org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy" \
   -H "Authorization: Bearer $ADMIN_TOKEN" \
   | python3 -c "
 import sys, json
 for p in json.load(sys.stdin):
     if p.get('providerId') == 'allowed-client-templates' and p.get('subType') == 'authenticated':
-        p['config']['allowed-client-scopes'] = ['agent:insights']
+        p['config']['allowed-client-scopes'] = ['api.console', 'api.ocm']
         print(json.dumps(p))
         break
 ")
@@ -1487,13 +1497,23 @@ echo "RED_HAT_SSO_CLIENT_ID=lightspeed-agent"
 echo "RED_HAT_SSO_CLIENT_SECRET=$CLIENT_SECRET"
 ```
 
-**Assign `agent:insights` to the Resource Server client:**
+**Assign `api.console` and `api.ocm` to the Resource Server client:**
 
 ```bash
 # Get the scope UUID
 SCOPE_UUID=$(curl -s "$KEYCLOAK_URL/admin/realms/test-realm/client-scopes" \
   -H "Authorization: Bearer $ADMIN_TOKEN" \
-  | python3 -c "import sys,json; print([s['id'] for s in json.load(sys.stdin) if s['name']=='agent:insights'][0])")
+  | python3 -c "import sys,json; print([s['id'] for s in json.load(sys.stdin) if s['name']=='api.console'][0])")
+
+# Add as optional scope to the client
+curl -s -X PUT \
+  "$KEYCLOAK_URL/admin/realms/test-realm/clients/$CLIENT_UUID/optional-client-scopes/$SCOPE_UUID" \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+
+# Get the api.ocm scope UUID
+SCOPE_UUID=$(curl -s "$KEYCLOAK_URL/admin/realms/test-realm/client-scopes" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  | python3 -c "import sys,json; print([s['id'] for s in json.load(sys.stdin) if s['name']=='api.ocm'][0])")
 
 # Add as optional scope to the client
 curl -s -X PUT \
@@ -1545,8 +1565,8 @@ echo -n "$CLIENT_SECRET" | \
     --data-file=- --project=$GOOGLE_CLOUD_PROJECT
 ```
 
-> **Note:** Keycloak assigns the `agent:insights` scope to DCR-created
-> clients because the DCR request includes `"scope": "agent:insights"` and
+> **Note:** Keycloak assigns the `api.console` and `api.ocm` scopes to DCR-created
+> clients because the DCR request includes `"scope": "api.console api.ocm"` and
 > the scope is in the Allowed Client Scopes registration policy (configured
 > above).  However, Keycloak does **not** enable `serviceAccountsEnabled`
 > from the DCR `grant_types` field.  After DCR, the agent automatically
@@ -1696,7 +1716,7 @@ python scripts/test_a2a_auth.py \
   --message "What systems have critical advisories?"
 ```
 
-The script requests `scope=openid agent:insights` via `client_credentials`
+The script requests `scope=openid api.console api.ocm` via `client_credentials`
 grant, then sends an A2A `message/send` request with the resulting Bearer token.
 
 To just get a token (e.g. for pasting into the A2A Inspector):

deploy/cloudrun/service.yaml

@@ -88,12 +88,10 @@ spec:
             # Red Hat SSO Configuration
             - name: RED_HAT_SSO_ISSUER
               value: "https://sso.redhat.com/auth/realms/redhat-external"
-            # OAuth scope required in access tokens (checked via introspection).
+            # Comma-separated OAuth scopes required in access tokens (checked via introspection).
             # Set to empty string to disable scope checking.
             - name: AGENT_REQUIRED_SCOPE
-              value: ""
-            # Replace with the required scopes if any is needed
-            #  value: "agent:insights"
+              value: "api.console,api.ocm"
             # Ensure production environment do not skip JWT validation
             - name: SKIP_JWT_VALIDATION
               value: "false"

deploy/podman/lightspeed-agent-configmap.yaml

@@ -15,7 +15,7 @@ data:
 
   # Red Hat SSO Configuration
   RED_HAT_SSO_ISSUER: "https://sso.redhat.com/auth/realms/redhat-external"
-  AGENT_REQUIRED_SCOPE: "agent:insights"
+  AGENT_REQUIRED_SCOPE: "api.console,api.ocm"
 
   # MCP Server Configuration (for agent)
   MCP_TRANSPORT_MODE: "http"

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 `agent:insights` scope
+- **Scope Checking**: Checks for required `api.console` and `api.ocm` scopes
 - **Bypass for Discovery**: `/.well-known/agent.json` is public per A2A spec
 
 ### Agent Core
@@ -222,7 +222,7 @@ acts purely as a Resource Server.
 
 ```
 1. Client authenticates directly with Red Hat SSO (e.g., client_credentials grant)
-2. Red Hat SSO issues access token with agent:insights scope
+2. Red Hat SSO issues access token with api.console and api.ocm scopes
 3. Client uses the token for A2A requests to the agent
 ```
 
@@ -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 `agent:insights` scope checked; returns 403 if missing
+- Required `api.console` and `api.ocm` scopes checked; returns 403 if missing
 
 ### Public Endpoints
 

docs/authentication-flow.md

@@ -146,7 +146,7 @@ Gemini Enterprise                     Agent (Marketplace Handler)             Re
    - `grant_types`: `authorization_code`, `refresh_token`, `client_credentials`
    - `token_endpoint_auth_method`: `client_secret_basic`
    - `redirect_uris`: from the Google JWT claims
-   - `scope`: `agent:insights`
+   - `scope`: `api.console api.ocm`
 5. Enables service accounts on the new client via the Keycloak Admin API (for
    `client_credentials` grant support).
 6. Encrypts the `client_secret` (Fernet symmetric encryption) and stores the
@@ -368,7 +368,8 @@ Customer User          Gemini Enterprise            Red Hat SSO (Keycloak)
      |   client_id=<ge_id>   |                              |                              |
      |   redirect_uri=<uri>  |                              |                              |
      |   scope=openid        |                              |                              |
-     |     agent:insights    |                              |                              |
+     |     api.console       |                              |                              |
+     |     api.ocm           |                              |                              |
      |   state=<csrf_state>  |                              |                              |
      |                       |                              |                              |
      |-- Follow redirect ----|----------------------------->|                              |
@@ -402,7 +403,7 @@ Customer User          Gemini Enterprise            Red Hat SSO (Keycloak)
      |                       |      token_type: "Bearer",   |                              |
      |                       |      expires_in: 300,        |                              |
      |                       |      scope: "openid          |                              |
-     |                       |        agent:insights"       |                              |
+     |                       |        api.console api.ocm"  |                              |
      |                       |    } ------------------------|                              |
      |                       |                              |                              |
      |                       |   [Access token obtained — user is authenticated]           |
@@ -420,7 +421,7 @@ Customer User          Gemini Enterprise            Red Hat SSO (Keycloak)
      (created via DCR or provided as static credentials)
    - `redirect_uri` = Gemini Enterprise's callback URL (from the registration
      `redirect_uris`)
-   - `scope` = `openid agent:insights`
+   - `scope` = `openid api.console api.ocm`
    - `state` = CSRF protection token
 3. The user sees the Red Hat SSO login page and authenticates with their
    **Red Hat credentials** (username/password, or federated SSO).
@@ -433,7 +434,7 @@ Customer User          Gemini Enterprise            Red Hat SSO (Keycloak)
    - The `client_id` and `client_secret` (HTTP Basic or POST body)
 6. Red Hat SSO returns an **access token** (JWT), a refresh token, and token
    metadata. The access token contains the user's identity claims and the
-   granted scopes (including `agent:insights`).
+   granted scopes (including `api.console` and `api.ocm`).
 
 **Key point:** The user authenticates with their Red Hat identity. The access
 token is issued by Red Hat SSO and represents both the user's identity and the
@@ -485,15 +486,16 @@ Gemini Enterprise                  Lightspeed Agent                      Red Hat
      |                                    |      "active": true,                  |
      |                                    |      "sub": "<user-id>",              |
      |                                    |      "azp": "<ge-client-id>",         |
-     |                                    |      "scope": "openid agent:insights",|
+     |                                    |      "scope": "openid api.console     |
+     |                api.ocm",             |
      |                                    |      "preferred_username": "jdoe",    |
      |                                    |      "email": "jdoe@example.com",     |
      |                                    |      "org_id": "<org-id>",            |
      |                                    |      "exp": 1234567890                |
      |                                    |    } ---------------------------------|
      |                                    |                                       |
      |                                    |-- Verify "active" == true             |
-     |                                    |-- Verify "agent:insights" in scopes   |
+     |                                    |-- Verify required scopes present      |
      |                                    |                                       |
      |                                    |-- Resolve order:                      |
      |                                    |   azp (ge-client-id)                  |
@@ -526,8 +528,9 @@ Gemini Enterprise                  Lightspeed Agent                      Red Hat
 
    c. **Validates** the introspection response:
       - `active` must be `true` (token is not expired/revoked).
-      - The `agent:insights` scope must be present in the token's scope list.
-        If missing, the agent returns `403 Forbidden`.
+      - The required scopes (`api.console` and `api.ocm`) must be present in
+        the token's scope list. If any are missing, the agent returns
+        `403 Forbidden`.
 
    d. **Resolves the order**: Uses the `azp` (authorized party) claim from
       the introspection response — this is the Gemini Enterprise `client_id`
@@ -571,13 +574,13 @@ Gemini Enterprise                  Lightspeed Agent                      Red Hat
      |                                    |                                       |
      |                                    |<-- { "active": true,                  |
      |                                    |      "scope": "openid" } -------------|
-     |                                    |   (missing agent:insights scope)      |
+     |                                    |   (missing required scopes)           |
      |                                    |                                       |
      |<-- 403 { code: -32003,             |                                       |
      |   message: "Forbidden",            |                                       |
      |   detail: "Token is missing        |                                       |
-     |     required scope:                |                                       |
-     |     agent:insights" } -------------|                                       |
+     |     required scope(s):             |                                       |
+     |     api.console, api.ocm" } -------|                                       |
      |                                    |                                       |
      |   --- OR ---                       |                                       |
      |                                    |                                       |
@@ -598,7 +601,7 @@ Gemini Enterprise                  Lightspeed Agent                      Red Hat
 | Token is expired or revoked (`active: false`) | 401 | -32001 | `Token is not active` |
 | 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 `agent:insights` scope | 403 | -32003 | `Token is missing required scope: agent:insights` |
+| Token missing required scope(s) | 403 | -32003 | `Token is missing required scope(s): api.console, api.ocm` |
 | `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` |
@@ -712,8 +715,9 @@ independently. This mode preserves the user's identity end-to-end.
 - **Order-bound access**: Every authenticated request is tied to an active
   marketplace order. Cancelled or expired subscriptions are immediately
   rejected.
-- **Scope-based authorization**: The `agent:insights` scope must be present
-  in the access token. Tokens without this scope receive `403 Forbidden`.
+- **Scope-based authorization**: The `api.console` and `api.ocm` scopes must
+  be present in the access token. Tokens without these scopes receive
+  `403 Forbidden`.
 - **Secrets encrypted at rest**: All client secrets stored in the database are
   encrypted with Fernet (symmetric AES-128-CBC with HMAC-SHA256).
 - **Token introspection (not local JWT verification)**: The agent validates