update mcp-gateway authn/authz guides

Signed-off-by: Patryk Stefanski <pstefans@redhat.com>

Author: Patryk-Stefanski

modules/proc-configure-mcp-gateway-authentication.adoc

@@ -18,7 +18,7 @@ The {mcpg} supports any Istio or Gateway API compatible authentication mechanism
 
 * You installed {mcpg}.
 * You installed {prodname}.
-* You configured a `Gateway` object.
+* You configured a `Gateway` object with an `mcp` listener.
 * You installed and have ready an identity provider supporting OAuth 2.0 or 2.1, for example, {keycloak}.
 
 .Procedure
@@ -105,7 +105,7 @@ spec:
           code: 401
           headers:
             'WWW-Authenticate':
-              value: Bearer resource_metadata=http://mcp.example.com:8001/.well-known/oauth-protected-resource/mcp
+              value: Bearer resource_metadata=http://mcp.example.com:8001/.well-known/oauth-protected-resource
           body:
             value: |
               {
@@ -127,18 +127,18 @@ spec:
 +
 [source,terminal,subs="+quotes"]
 ----
-$ oc apply -f _<mcp_jwt_authpolicy.yaml>_
+$ oc apply -f - <<EOF
+<AuthPolicy CR from the previous step>
+EOF
 ----
-+
-Replace `_<mcp_jwt_authpolicy.yaml>_` with the name of your CR.
 
 .Verification
 
 . Test that the broker now serves OAuth discovery information by checking the protected resource metadata endpoint with the following command:
 +
 [source,terminal,subs="+quotes"]
 ----
-$ curl http://_<mcp.example.com:8001/.well_known/oauth_protected_resource>_
+$ curl http://_<mcp.example.com:8001>_/.well-known/oauth-protected-resource
 ----
 +
 * Replace the URL with your protected resource information.

modules/proc-mcp-gateway-authorization.adoc

@@ -1,4 +1,3 @@
-
 // Module included in the following assemblies:
 //
 // *mcp_gateway_config/mcp-gateway-authorization.adoc
@@ -14,12 +13,40 @@ The following example demonstrates using a Kuadrant `AuthPolicy` custom resource
 
 * You installed {mcpg}.
 * You installed {prodname}.
-* You configured a `Gateway` object.
-* You completed authentication procedures.
+* You configured a `Gateway` object with an `mcp` listener.
+* You completed authentication procedures, including creating an `AuthPolicy` CR on the `mcp` listener.
 * You configured your identity provider to include `group` and `role` claims in JSON Web Tokens (JWT).
+* The identity provider client IDs match the namespaced `MCPServerRegistration` name in the format `_<namespace>_/_<mcpserverregistration_name>_`.
 
 .Procedure
 
+. Add an `mcps` listener to the `Gateway` object for internal `tools/call` routing by using the following command as an example:
++
+[source,json,subs="+quotes"]
+----
+$ oc patch gateway _<mcp_gateway>_ -n _<gateway_system>_ --type json -p '[
+  {
+    "op": "add",
+    "path": "/spec/listeners/-",
+    "value": {
+      "name": "mcps",
+      "port": 8080,
+      "protocol": "HTTP",
+      "hostname": "*.mcp-internal.example.com",
+      "allowedRoutes": {
+        "namespaces": {
+          "from": "All"
+        }
+      }
+    }
+  }
+]'
+----
++
+* Replace `_<mcp_gateway>_` with the name of your MCP gateway.
+* Replace `_<gateway_system>_` with the namespace of your `Gateway` object.
+* Replace `*.mcp-internal.example.com` with a wildcard hostname for your environment.
+
 . Ensure that your identity provider includes the required `group` and `role` claims in the issued JWTs. In the following example, {keycloak} is used:
 +
 .Example issued OAuth token claims:
@@ -37,10 +64,15 @@ The following example demonstrates using a Kuadrant `AuthPolicy` custom resource
 }
 ----
 +
-* The `"mcp-ns/arithmetic-mcp-server"` specification must match the namespaced name of the `MCPServerRegistration` CR.
+* The `"mcp-ns/arithmetic-mcp-server"` specification must match the namespaced name of the `MCPServerRegistration` CR in the format `{namespace}/{name}`. For example, if your `MCPServerRegistration` is named `arithmetic-mcp-server` in the `mcp-ns` namespace, the {keycloak} client ID must be `mcp-ns/arithmetic-mcp-server`.
 * The `"roles": ["add", "sum", "multiply", "divide"]` parameter and values specify the roles representing the allowed tools.
 
-. Configure tool-level authorization by creating an `AuthPolicy` CR that enforces tool-level access control, as shown in the following example:
+. Configure tool-level authorization by creating an `AuthPolicy` CR that enforces tool-level access control on the `mcps` listener, as shown in the following example:
++
+[IMPORTANT]
+====
+The authorization `AuthPolicy` must target the `mcps` listener, not the `mcp` listener. The `mcp` listener handles public traffic (`initialize`, `tools/list`, `/.well-known`) and has the authentication-only `AuthPolicy`.
+====
 +
 .Example tool-level access control AuthPolicy
 [source,yaml,subs="+quotes"]
@@ -60,7 +92,7 @@ spec:
     authentication:
       'sso-server':
         jwt:
-          issuerUrl: http://keycloak.example.com:8002/realms/mcp
+          issuerUrl: https://_<keycloak.example.com>_/realms/mcp
     authorization:
       'tool-access-check':
         patternMatching:
@@ -71,7 +103,7 @@ spec:
       unauthenticated:
         headers:
           'WWW-Authenticate':
-            value: Bearer resource_metadata=http://mcp.example.com:8001/.well-known/oauth-protected-resource/mcp
+            value: Bearer resource_metadata=http://_<mcp.example.com:8001>_/.well-known/oauth-protected-resource
         body:
           value: |
             {
@@ -90,8 +122,8 @@ spec:
 * Replace `metadata.name:` with the name of the `AuthPolicy`.
 * Replace `metadata.namespace:` with the namespace where the `AuthPolicy` CR is applied.
 * Replace `spec.targetRef.name:` with the name of the `Gateway` CR.
-* The `spec.targetRef.sectionName:` value targets the MCP server listener.
-* Authentication: Validates the JWT token using the configured issuer URL
+* The `spec.targetRef.sectionName:` value must be `mcps`, the internal listener for tool-call authorization. This listener must exist on your `Gateway` object.
+* Authentication: Validates the JWT token using the configured issuer URL. Replace `_<keycloak.example.com>_` with your identity provider hostname.
 * Authorization Logic: CEL expression checks if user's roles allow access to the requested tool
 * CEL Breakdown:
 ** `request.headers['x-mcp-toolname']`: The name of the requested MCP tool, stripped from prefix.
@@ -103,24 +135,24 @@ spec:
 +
 [source,terminal,subs="+quotes"]
 ----
-$ oc apply -f _<mcp_tool_auth_policy.yaml>_
+$ oc apply -f - <<EOF
+<AuthPolicy CR from the previous step>
+EOF
 ----
-* Replace `_<mcp_tool_auth_policy.yaml>_` with the name of the `AuthPolicy` YAML filename.
 
 .Verification
 
 . Monitor authorization decisions by checking the `AuthPolicy` CR `status` with the following command:
 +
-[source,terminal]
+[source,terminal,subs="+quotes"]
 ----
-$ oc get authpolicy -A
+$ oc get authpolicy _<mcp_tool_auth_policy>_ -n _<gateway_system>_ -o jsonpath='{.status.conditions[?(@.type=="Enforced")].status}'
 ----
 +
 .Example output
 [source,text]
 ----
-NAMESPACE        NAME                    STATUS
-gateway-system   mcp-tool-auth-policy    Enforced
+True
 ----
 
 . Check the authorization logs by running the following command: