docs: split-horizon backchannel discovery for private-VPC OIDC

[oren-openteams]

Summary

Adds a new Split-horizon backchannel discovery (private-VPC deployments) section to docs/auth-flow.md, plus a brief callout in the README pointing at it. Covers the gap between the front-channel OAuth flow (already well-documented) and what pack authors need to know when their backend calls Keycloak endpoints directly on a private-VPC cluster.

Motivation

The existing auth-flow.md covers the browser-to-Envoy-to-Keycloak front-channel flow in depth (11-step diagram, cookie format, JWT decoding, etc.) but doesn't address what happens when a pack's backend service needs to hit Keycloak itself — for token validation, refresh, JWKS fetch, or userinfo introspection.

On a private-VPC cluster, this is where things get subtle:

• The issuerURL (external hostname) is what tokens are stamped with, so consumers must validate iss against it
• BUT reaching that external URL from in-cluster often requires egress proxy trust or DNS gymnastics
• The clean pattern is to split: issuerURL for validation, discoveryURL pointed at Keycloak's in-cluster Service for the actual OIDC handshake

Every downstream pack author using this template will hit this problem the moment they deploy on a real cluster. Documenting the pattern here (rather than each pack re-discovering it) saves the community time.

What the new section covers

• Why the split-horizon pattern exists (external iss claim + in-cluster reachability)
• The complementary KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true setting on the Keycloak side (makes Keycloak return backchannel URLs based on how it was reached)
• Recommended chart values shape (keycloak.hostname, keycloak.serviceHost, keycloak.realm, auth.oidc.{issuerURL,discoveryURL}) with helper template fall-through
• Reference implementation link: nebari-dev/nebi-pack#34 (merged today)
• Explicit callout of when this does NOT apply — packs that only read the IdToken cookie don't need any of this

Reference implementation

Nebi-pack #34 lands the exact pattern documented here. Validated downstream on a real private-VPC cluster via ArgoCD: the default helper produces the correct in-cluster URL, nebi initializes cleanly, OIDC discovery succeeds. See the PR#34 comment thread for evidence.

Placement

• docs/auth-flow.md: new ## Split-horizon backchannel discovery (private-VPC deployments) section, positioned between the existing App-Native OAuth section and NebariApp CRD vs Envoy Gateway SecurityPolicy section. That's the natural taxonomy — App-Native OAuth introduces the "your app talks to Keycloak" concept; this new section covers "and here's how to do it correctly on a private-VPC cluster."
• README.md: 5-line callout added to the existing ## How Authentication Works section, linking to the new deep-dive.