Skip to content

Add qualified service account route sources - #603

Draft
rkoster wants to merge 8 commits into
cloudfoundry:developfrom
rkoster:service-accounts-poc
Draft

rkoster wants to merge 8 commits into
cloudfoundry:developfrom
rkoster:service-accounts-poc

Conversation

@rkoster

@rkoster rkoster commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Implement qualified service-account route sources for RFC 0065, building on RFC 0055.

  • Match cf:svc:<org-prefix>:<account-name> against <account-name>.<org-prefix>.svc.identity from the caller's certificate (exactly one well-formed SAN; zero, several or malformed *.svc.identity SANs yield no account).
  • Take the whole caller identity (app, space, org and account) from the XFCC data, so no field comes from a different source than the others. With sanitize_set that data is derived from the verified peer certificate; forward and always_forward trust the forwarded header for every field alike, as before for app, space and org.
  • In the envoy XFCC format GoRouter adds SVC=<SAN> between Hash and Subject when the certificate has a service account. It is read only from ahead of the Subject, so nothing certificate-controlled can introduce one. Other DNS SANs are never exposed. The raw format already carries the SANs in the certificate.
  • Log malformed-route-policy for cf:svc: rules that are not cf:svc:<label>:<label> (lowercase RFC 1123 labels, 3-63 characters), like other unrecognized rules.
  • Preserve existing app/space/org/any source semantics, domain caller-scope restrictions and default deny.

Ship routing support before the CAPI producer changes. No router contract-version configuration is required; old routers deny unmatched account sources.

Note for RFC 0055: SVC= is a GoRouter extension to the Envoy-style compact format.

Committed TDD

  • RED 3003dc3cf -> GREEN bec37471a: verified certificate SAN extraction and exact source matching.
  • RED 13f6637f9 -> GREEN 839fe82c2: warning for malformed account rules.
  • RED 093a22fe9 -> GREEN 8af4d1633: single-source identity and SVC= (including the case where a client-supplied header in a forward mode could be combined with an account taken from the TLS leaf).
  • ff762ec82: integration coverage of behavior already implemented (no RED).
  • 7d84c2219: job spec description of the envoy format.

Tests

Ginkgo coverage in handlers, handlers/postselection and integration: SAN matrix over both XFCC formats, emission and parsing of SVC=, header-injection cases, forward modes, end-to-end scope and route-policy authorization, and 29 integration specs over real mutual-TLS handshakes (forged XFCC, scope, forward-mode domain).

All ./gorouter/... packages except integration and router pass. integration service-account specs pass (NATS_SERVER_BINARY required). router could not run in the authoring environment because *.localhost.routing.cf-app.com does not resolve; this is not claimed as passing. Release template specs were not run (gems unavailable).

Current homelab evidence — 2026-11-20

Head 7d84c2219 built/uploaded as routing 0.0.0+dev.20261120130000; dry-run task34075 and deployment task34076 succeeded with the existing lab skip-drain setting. Candidate changed only the routing release version; other component versions and identity-aware routing configuration were preserved. All monitored processes are running.

Direct mTLS requests with server certificate validation, on the existing sanitize_set/envoy domain:

  • Two apps sharing an account in distinct entitled spaces: HTTP200; the backend sees SVC=qualified-worker.homelab-poc.svc.identity, and no DNS= elements.
  • Forged XFCC on the authorized caller is replaced: HTTP200 with its genuine account at the backend.
  • Wrong-account and unbound callers: HTTP403, also when they forge SVC=.
  • No client certificate: TLS handshake rejected.
  • Existing space-scoped route: same-space caller200, other-space caller403 despite the shared account.

Forward-mode trust and malformed-rule warning are covered by component/integration tests; this live deployment uses sanitize_set. No GitHub Actions workflow exists in routing-release and no Actions run was created for this head; EasyCLA passes. Remaining broad regression verification depends on upstream CI/maintainers.

Earlier homelab evidence

Routing 0.0.0+dev.20261110100000 deployed successfully in BOSH task33969, before CAPI task33971.

  • Both apps sharing an account across entitled spaces: HTTP200 on the account-only route.
  • Wrong account, unbound app and spoofed XFCC: HTTP403.
  • No client certificate: TLS handshake rejected.
  • Space-scoped route: same-space caller200, other-space caller403 despite the shared account.
  • Final deployment health: all monitored processes running.

Direct verified TLS is demonstrated; external trusted-proxy SAN forwarding is not demonstrated by this change.

Ginkgo coverage for cf:svc:<prefix>:<name> matching and denial, and the malformed-route-policy warning for malformed account rules. Matching cases already pass; the malformed-rule warning cases fail until the account source syntax is validated.
Validate cf:svc: rules against the cf:svc:<prefix>:<name> syntax (lowercase RFC 1123 labels, 3-63 characters) and log malformed-route-policy before skipping them, as other unrecognized rules already do.
Replace the plain Go test with Ginkgo coverage of service-account caller identity: SVC= emission in the envoy XFCC format, SVC= parsing, a single trust source for app, space, org and account in forward modes, header-injection guards and end-to-end route-policy and domain-scope authorization. Specs for the new SVC= key and for forward-mode sourcing fail until the identity handler stops mixing the verified TLS leaf with forwarded header data.
Emit the validated account as SVC=<san> ahead of the Subject in the envoy XFCC format and read it back only from ahead of the Subject, so nothing in a certificate-controlled value can introduce one. The raw format reads the account from the header certificate's SANs. App, space, org and account now all come from the XFCC data, no longer partly from the TLS connection: sanitize_set derives it from the verified peer certificate, and forward modes trust the forwarded header for every field alike.
Integration coverage over real mutual-TLS handshakes with Diego-style instance certificates carrying zero, one or several service-account SANs: matching and non-matching accounts, a malformed rule beside a valid one, domain scope, client-forged XFCC headers in sanitize_set, and a forward-mode domain. These exercise behavior already implemented, so there is no preceding red commit.
The envoy format adds SVC=<SAN> between Hash and Subject when the client certificate has exactly one service-account SAN.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

1 participant