A contract for registering a client app behind the SSO gate

[AE-EVKA]

Feature description

ADR-0001 describes client projects building on SRDP. There is no supported mechanism for the final
step: placing a client app behind Traefik + oauth2-proxy + Zitadel. Client projects hand-write
Traefik labels against SRDP internals.

Use case

Adding the datavloot dashboard to the Compose stack required:

• Traefik labels matching zitadel-auth@docker, zitadel-errors@docker, the srdp-app network and
  router naming conventions.
• Replacing the entire oauth2-proxy command to add one scope
  (urn:zitadel:iam:org:projects:roles), needed so Zitadel asserts project roles in the token.
• Overriding Traefik authResponseHeaders to forward X-Auth-Request-Access-Token.

The third item is the notable one. The default forwards X-Auth-Request-User and
X-Auth-Request-Email and withholds the access token. ADR-0008 says not to trust the former and to
validate the latter. A client app following ADR-0008 must reconfigure Traefik to do so.

Proposed solution

1. A declarative way to register an app. Options, in preference order:
   • a stanza in srdp.toml (Proposal: srdp.toml, a single platform config #42) that renders the labels
   • an x-srdp-app: Compose extension field
   • a documented labels fragment to include
2. scopes as configuration rather than a full command override.
3. authResponseHeaders as configuration, with the access token included by default.

Alternatives considered

Alternative	Why not
Hand-written labels (current)	Couples every client to SRDP internals; breaks silently on rename
Fork the compose file	Loses upstream changes
Run client apps outside the gate	Defeats single sign-on; contradicts the client-project model
Wait for #42	Possibly correct. If srdp.toml is the intended home, close this and fold it in

Component

deploy/docker, services/traefik, services/oauth2-proxy

[yannick-vinkesteijn]

Will be picked up via #42 (srdp.toml), see ADR-0011.

[AE-EVKA]

Status update from testing, for whoever picks this up under ADR-0011:

• Routing: Compose: configurable domain and extendable Traefik routing #91 proposes an interim mechanism: a client project mounts its own route file next to SRDP's. Tested on v0.3.1 with an overlay: the route is gated, an existing session works on it, and no SRDP files are edited.
• Access token forwarding: done on main. X-Auth-Request-Access-Token is in authResponseHeaders.
• Scopes: no change needed. The oauth2-proxy command doesn't set --scope, so an overlay can set OAUTH2_PROXY_SCOPE in the environment. Tested: the authorize request carries the extra scope and Zitadel accepts it.

What's left here is the declarative part (an entry that renders the route), which ADR-0011 covers. One input for that design: the client's host also needs a redirect URI on the oauth2-proxy OIDC app. I haven't tested whether it's required. If it is, that fits the setup service (#60).