[jhrozek]

Closes #6893

Summary

Operators can only configure a pre-provisioned delegate client for RFC 8693 token exchange through the RunConfig today. The operator CRD cannot express the key-based (private_key_jwt) form that the auth server supports, so a broker that rotates its key has to edit the RunConfig by hand. This PR exposes the delegate client settings on the operator API and wires them through to the auth server.

What changed:

• The delegate client on MCPExternalAuthConfig and VirtualMCPServer gains tokenEndpointAuthMethod, jwksRef (a ConfigMap key holding the public JWKS), tokenEndpointAuthSigningAlg, grantTypes, redirectUris, and a tokenExchange policy block. Admission rules mirror the runtime validator for the cases CEL can express.
• The operator mounts each jwksRef read-only and points the RunConfig jwks_file at it.
• The pod rolls when a referenced JWKS ConfigMap changes. The JWKS bytes are part of the pod-template checksum, so the next reconcile restarts the auth server with the new keys. Without this, a key rotation would never reach a running pod.
• A VirtualMCPServer whose delegate clients are configured only on the canonical inboundGrants.tokenExchange list is now accepted. The runtime validator previously counted only the deprecated top-level list, so such a server was rejected at reconcile.
• The trust-mode error for a private_key_jwt delegate without a token_exchange block now names the one-line change that keeps the old behaviour.
• Architecture docs for the auth server and the operator describe the CRD fields and the rollout behaviour.

Type of change

• Bug fix
• New feature
• Refactoring (no behavior change)
• Dependency update
• Documentation
• Other (describe):

Test plan

• Unit tests (task test): run, exit 0, no failure output. The run includes the new validator test for canonical delegate clients.
• E2E tests: focused Ginkgo run of the new kind suite VirtualMCPServer delegate client jwksRef on a kind cluster built from this branch. 4 of 4 specs passed: the read-only mount with a matching-key exchange, a wrong key under a registered kid, a foreign subject token refused under restricted, and a two-stage key rotation with a pod roll.
• Linting (task lint-fix): not run yet.
• Manual testing: none beyond the kind suite.

The envtest CEL suite in cmd/thv-operator/test-integration/mcp-external-auth/delegate_client_cel_test.go has been written but not run. It is the check for the admission rules and should be run before merge.

API Compatibility

• This PR does not break the v1beta1 API. Every new field is optional. The only other change is that the deprecated top-level delegateClients now rejects the new fields. Those fields do not exist on main, so no stored object is affected.

Does this introduce a user-facing change?

Yes. Before: the operator CRD could not configure a private_key_jwt delegate client, and a VirtualMCPServer that configured delegates only on inboundGrants.tokenExchange was rejected at reconcile. After: both work. Specifically:

• New delegate client fields on MCPExternalAuthConfig and VirtualMCPServer, documented in the CRD reference.
• Editing a referenced JWKS ConfigMap rolls the auth server pod. Editing it does not hot-reload the keys.
• The deprecated top-level delegateClients rejects the new fields and points users at inboundGrants.tokenExchange.delegateClients.
• Redirect URIs must be https with no fragment. A loopback redirect URI is refused when the operator reconciles, and the resource reports it in its status conditions. The API server does not refuse it at admission, because the operator has no admission webhook.

Special notes for reviewers

• The trust-mode requirement for private_key_jwt delegates is already on main (Require a trust mode for private_key_jwt delegates #7004). This PR only changes the error text.
• Loopback redirect URIs are refused at reconcile, not at admission. CEL cannot express loopback reliably, and there is no webhook. Status reporting is the accepted behaviour, following the existing forceConfidentialRedirectUris precedent.
• The JWKS reference uses a new local ConfigMapKeyRef type rather than corev1.ConfigMapKeySelector, so optional cannot be set and both name and key are required.
• The generated CRD YAML is most of the diff. It appears once per copy under deploy/charts/operator-crds/files and templates, across both MCPExternalAuthConfig and VirtualMCPServer.
• Exchange refresh tokens are not part of this PR. They follow in a separate PR with their own end-to-end coverage.
• The commit history is one logical change per commit, with the comment and migration-hint commits riding along.

[codecov]

Codecov Report

❌ Patch coverage is 95.23810% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.50%. Comparing base (a148949) to head (4ea59c0).

Files with missing lines	Patch %	Lines
cmd/thv-operator/pkg/controllerutil/authserver.go	95.55%	4 Missing ⚠️
...or/controllers/virtualmcpserver_authz_configmap.go	85.00%	3 Missing ⚠️
...perator/api/v1beta1/mcpexternalauthconfig_types.go	98.07%	1 Missing ⚠️
...perator/controllers/virtualmcpserver_deployment.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7019      +/-   ##
==========================================
+ Coverage   80.48%   80.50%   +0.02%     
==========================================
  Files         853      853              
  Lines       87121    87256     +135     
==========================================
+ Hits        70118    70247     +129     
- Misses      16998    17004       +6     
  Partials        5        5              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jhrozek]

Please hold off on reviewing this one for now.

This PR exposes tokenExchange.apiAudience in the CRD, with a rule that it must be one of the client's audiences and a field doc saying the client may request it even when the subject token doesn't cover it. That's the behaviour the fix for "Configured delegate client with api_audience can exchange for API access tokens" (#7026) removes.

The fix lands first. After that I'll rework this PR to the new shape before it merges: subjectTokenAudiences as an input-only list (only valid with selfIssuedSubjectTokens: restricted), and audiences as outputs only. The CRD field hasn't been released, so there's nothing to migrate. I'll leave another note when it's ready for review again.

[jhrozek]

This is rebased onto exchange-grant-offline-access, so it now sits on the stack below it. The field is now subjectTokenAudiences, a list matched exactly against the subject token's aud, which replaces the single apiAudience. Operator unit tests and the envtest integration suite pass locally. This is ready for review, and the earlier hold note no longer applies.

[jhrozek]

Moving this back to draft, and I know I said earlier today that it was ready. Sorry for the churn.

Since then I looked at who would use the operator side of this, and I can't name anyone yet. The one consumer I know of for private_key_jwt delegate clients builds the RunConfig in process and doesn't go through the CRD. So nothing I can point to needs jwksRef, the pod roll, or the extra client fields. For grantTypes and redirectUris I can't name a use case at all.

The cost of guessing is the CRD shape. These fields are v1beta1, so we'd have to keep them. The RunConfig is only used by our own code, so it can change when we learn more. The audience fields in this stack changed shape twice in two days. That was free only because nobody could depend on them yet.

I'll open a separate PR for the parts that help RunConfig users: the vMCP validator fix (a config with delegate clients only under inbound_grants was rejected), plus a test and docs for rotating a delegate client's key. This one stays in draft until a deployment needs it through the CRD, for example a gateway administrator who has to rotate a broker's key without hand-editing the RunConfig. If you have one in mind, please say so here. No need to review it until then.