Sync primaryUpstreamProvider guidance in user-facing docs

Two user-facing docs and one in-code constant comment had drifted
relative to the schema and runtime behaviour shipped earlier on this
branch. The schema docstrings and CRD reference were already in sync
with the code; this commit catches up the prose that users actually
read first.

* `docs/operator/virtualmcpserver-api.md`: the `authzConfig` section
  listed `primaryUpstreamProvider` under `inline` with no deprecation
  note, did not mention the new top-level claim-mapping fields on
  `AuthzConfigRef`, and did not document the failure modes on
  `AuthConfigured`. The new prose marks the inline location as
  deprecated, points to
  `spec.authServerConfig.primaryUpstreamProvider`, describes
  `groupClaimName` / `roleClaimName` / `groupEntityType` with their
  spec-over-ConfigMap precedence, and names the
  `AuthzConfigMapNotFound` / `AuthzConfigMapInvalid` reasons users
  will see on misconfiguration. Addresses F2.

* `docs/operator/virtualmcpserver-kubernetes-guide.md`: the
  "Multiple upstream IDPs" troubleshooting block pinned
  `primaryUpstreamProvider` at the deprecated inline location, so
  anyone following the guide would emit
  `AuthzPrimaryUpstreamProviderDeprecated` events on every reconcile.
  The example now uses `spec.authServerConfig.primaryUpstreamProvider`.
  Adds a "Migration: `primaryUpstreamProvider` location" note that
  names the deprecation event reason and the planned removal cadence.
  Adds an "Authorization policy errors" subsection covering
  `AuthzConfigMapNotFound` / `AuthzConfigMapInvalid` and an
  "Enterprise Cedar policies that deny every request" subsection
  covering the claim-mapping knobs. Addresses F3, F7, and F13.

* `cmd/thv-operator/api/v1beta1/mcpserver_types.go`:
  `ConditionTypeAuthzPrimaryUpstreamProviderIgnored` now carries the
  deprecation lineage in its doc comment. The condition fires only
  for the deprecated `InlineAuthzConfig.PrimaryUpstreamProvider`
  field; when that field is removed at end of the deprecation cycle,
  this condition and its reason constant should be removed in the
  same change. Addresses Jakub's PR-level nit.

No code changes; comment and prose only.

Author: blkt

cmd/thv-operator/api/v1beta1/mcpserver_types.go

@@ -96,6 +96,12 @@ const (
 	// when spec.authzConfig.inline.primaryUpstreamProvider is non-empty on a CR type
 	// that has no embedded auth server (MCPServer / MCPRemoteProxy). The field has
 	// no effect on those resources and is documented as VirtualMCPServer-only.
+	//
+	// Tied to the deprecated InlineAuthzConfig.PrimaryUpstreamProvider field
+	// (see mcpserver_types.go). When that field is removed at end of the
+	// deprecation cycle, this condition and ConditionReasonAuthzPrimaryUpstreamProviderIgnored
+	// below should be removed in the same change: there is no other path that
+	// fires this advisory.
 	ConditionTypeAuthzPrimaryUpstreamProviderIgnored = "AuthzPrimaryUpstreamProviderIgnored"
 )
 

docs/operator/virtualmcpserver-api.md

@@ -86,14 +86,32 @@ Configures authentication for clients connecting to the Virtual MCP server. Reus
   - `type` (string, required): `inline` or `configMap`
   - `inline` (InlineAuthzConfig, required when type=inline): Inline Cedar policies
     - `policies` ([]string, required): Cedar policy strings
-    - `entitiesJson` (string, optional): Cedar entities (JSON)
-    - `primaryUpstreamProvider` (string, optional): Names the upstream IDP whose
-      access token claims Cedar should evaluate. Only meaningful when
-      `spec.authServerConfig` is set with multiple upstreamProviders. When
-      empty, the controller defaults to the first upstream. Must match a
-      configured upstream name; the VirtualMCPServer is rejected with
-      `AuthServerConfigValidated=False` otherwise.
-  - `configMap` (ConfigMapAuthzRef, required when type=configMap): Reference to a ConfigMap holding policies
+    - `entitiesJson` (string, optional): Cedar entities (JSON). Required when
+      transitive policies (e.g. `ClaimGroup` → `PlatformRole`) need a static
+      entity store. Defaults to `"[]"`.
+    - `primaryUpstreamProvider` (string, optional): **Deprecated.** Use
+      `.spec.authServerConfig.primaryUpstreamProvider` instead. Setting this
+      field still resolves a primary upstream for backward compatibility and
+      emits a Warning event with reason
+      `AuthzPrimaryUpstreamProviderDeprecated`. Planned removal one release
+      after the deprecation cycle.
+  - `configMap` (ConfigMapAuthzRef, required when type=configMap): Reference to
+    a ConfigMap holding Cedar policies. The operator resolves the ConfigMap at
+    reconcile time and bakes the policies into the rendered vmcp `config.yaml`.
+    Failures surface as `AuthConfigured=False` with reason
+    `AuthzConfigMapNotFound` (missing reference) or `AuthzConfigMapInvalid`
+    (parse, validation, or non-Cedar payload).
+  - `groupClaimName` (string, optional): JWT claim key Cedar should treat as
+    the group list (overrides the well-known defaults `groups`, `roles`,
+    `cognito:groups`). When `type` is `configMap`, the spec value overrides
+    any `group_claim_name` set in the ConfigMap payload.
+  - `roleClaimName` (string, optional): JWT claim key Cedar should treat as
+    the role list. Same spec-over-ConfigMap precedence as `groupClaimName`.
+  - `groupEntityType` (string, optional): Cedar entity type used for principal
+    parent UIDs synthesised from JWT group/role claims. Defaults to
+    `THVGroup`. Must match the entity type used in the static entity store
+    for transitive `in` checks to resolve. Same spec-over-ConfigMap
+    precedence as `groupClaimName`.
 
 **Important**: The `type` field must always be explicitly specified. When no authentication is required, use `type: anonymous`.
 

docs/operator/virtualmcpserver-kubernetes-guide.md

@@ -628,17 +628,68 @@ Then gradually add restrictions. Common Cedar policy issues:
 **Multiple upstream IDPs**: when `spec.authServerConfig` declares more than
 one `upstreamProviders` entry, Cedar evaluates claims from the first one by
 default. Pin a specific provider explicitly via
-`authzConfig.inline.primaryUpstreamProvider`:
+`spec.authServerConfig.primaryUpstreamProvider`:
 
 ```yaml
-authzConfig:
-  type: inline
-  inline:
+spec:
+  authServerConfig:
+    issuer: https://vmcp.example.com
     primaryUpstreamProvider: okta   # must match one of the configured upstreams
-    policies:
-      - 'permit(principal, action, resource);'
+    upstreamProviders:
+      - name: okta
+        type: oidc
+        # ...
+      - name: github
+        type: oauth2
+        # ...
+  incomingAuth:
+    authzConfig:
+      type: inline
+      inline:
+        policies:
+          - 'permit(principal, action, resource);'
 ```
 
+> **Migration: `primaryUpstreamProvider` location**
+>
+> The field used to live under
+> `spec.incomingAuth.authzConfig.inline.primaryUpstreamProvider`. It has
+> moved to `spec.authServerConfig.primaryUpstreamProvider` to sit next to
+> the `upstreamProviders` list it selects from. The old location is read
+> for one release for backward compatibility; the controller emits a
+> Warning event with reason `AuthzPrimaryUpstreamProviderDeprecated`
+> whenever it consumes the deprecated location. Move the value to the new
+> location to clear the warning. The deprecated field is planned for
+> removal one release after the deprecation cycle.
+
+**Authorization policy errors**: misconfigured authz surfaces on the
+`AuthConfigured` condition with one of:
+
+* `AuthzConfigMapNotFound`: the ConfigMap referenced by
+  `spec.incomingAuth.authzConfig.configMap` does not exist in the
+  namespace. Create it before reconciling, or fix the name.
+* `AuthzConfigMapInvalid`: the ConfigMap exists but the payload is
+  missing the configured key, empty, malformed YAML/JSON, fails Cedar
+  validation, or is a registered non-Cedar authorizer (vMCP supports
+  Cedar only). Check the payload shape (see the Cedar v1 schema in the
+  example above).
+
+**Enterprise Cedar policies that deny every request**: when a policy
+walks a transitive hierarchy like `Client → ClaimGroup → PlatformRole`,
+both Cedar JWT-claim mapping settings and the static entity store must
+agree on the entity type. The configuration fields live on
+`spec.incomingAuth.authzConfig`:
+
+* `groupClaimName` / `roleClaimName`: JWT claim keys to extract.
+* `groupEntityType`: Cedar entity type used for principal parent UIDs.
+  Must match the entity type used in `entitiesJson` (e.g. `ClaimGroup`
+  rather than the default `THVGroup`).
+
+For configMap-sourced authz, the same fields can be set in the
+ConfigMap payload (`cedar.group_claim_name`, `cedar.role_claim_name`,
+`cedar.group_entity_type`); spec-level values on `authzConfig` override
+the ConfigMap when set.
+
 ### Backend Discovery Issues
 
 #### Backends Not Discovered