feat(gateway-api): GitHub SSO via oauth2-proxy in front of dsh-gateway (#13)

Add oauth2-proxy (GitHub provider, org-restricted) as a reverse proxy in
front of the dsh-gateway, wired through the Traefik Gateway API. The gateway
inherits the authenticated GitHub username via X-Forwarded-User (SSO).

- gateway.py: opt-in AUTH_PROXY_HEADER trust, remote_user(), SSO bootstrap
  (auto-provision claim + mint/rotate token + session cookie), patch_token()
- 50-gateway.yaml: AUTH_PROXY_HEADER=X-Forwarded-User, COOKIE_SECURE=true
- gateway-api/dsh-demo: oauth2-proxy Deployment/Service + secret example,
  HTTPRoute backend -> oauth2-proxy:4180
- tests: 10 new SSO cases (106 passing)

Placeholders (dsh-demo.example.com, your-github-org) are substituted at
apply time.

Co-authored-by: SREDevOpsAgents <agents@sredevops.org>

examples/dsh-agents-as-a-service/50-gateway.yaml

@@ -118,7 +118,14 @@ spec:
             # 60-ingress.yaml with TLS); "false" keeps the plain-HTTP demo
             # usable via port-forward.
             - name: COOKIE_SECURE
-              value: "false"
+              value: "true"
+            # Trusted reverse-proxy identity header for SSO. oauth2-proxy sets
+            # X-Forwarded-User to the authenticated GitHub login on every request;
+            # the gateway trusts it (and auto-provisions the user) only when this
+            # is set. Remove/unset to disable SSO and fall back to bearer/session
+            # auth only.
+            - name: AUTH_PROXY_HEADER
+              value: X-Forwarded-User
             # Reject proxied request bodies larger than this (413).
             - name: MAX_BODY_MB
               value: "32"

examples/dsh-agents-as-a-service/gateway/gateway.py

@@ -331,6 +331,11 @@ class Settings:
     # Connection retries while a Ready pod is still binding its port.
     upstream_attempts: int = 3
     upstream_retry_delay: float = 1.0
+    # Optional identity header (e.g. "X-Forwarded-User") set by an authenticating
+    # reverse proxy such as oauth2-proxy. When configured, requests carrying a
+    # valid user in this header are treated as authenticated (SSO); unset (None)
+    # disables SSO entirely and the header is never trusted.
+    auth_proxy_header: str | None = None
 
     @classmethod
     def from_env(cls) -> Settings:
@@ -348,6 +353,7 @@ class Settings:
             max_body_bytes=_env_int("MAX_BODY_MB", 32) * 1024 * 1024,
             http_timeout=_env_float("HTTP_TIMEOUT", 300.0),
             sweep_interval=_env_float("SWEEP_INTERVAL", 15.0),
+            auth_proxy_header=os.environ.get("AUTH_PROXY_HEADER") or None,
         )
 
 
@@ -496,6 +502,18 @@ class Kubernetes:
             {"spec": {"operatingMode": mode}},
         )
 
+    async def patch_token(self, user: str, token_hash: str) -> None:
+        await self._call(
+            "crd",
+            "patch_namespaced_custom_object",
+            GROUP,
+            VERSION,
+            self.namespace,
+            "sandboxclaims",
+            claim_name(user),
+            {"metadata": {"annotations": {TOKEN_ANNOTATION: token_hash}}},
+        )
+
     # -- pods and logs -----------------------------------------------------
 
     async def get_pod(self, name: str) -> dict | None:
@@ -571,17 +589,67 @@ class Gateway:
                 return token, user
         return None, None
 
+    def remote_user(self, headers) -> str | None:
+        """The user asserted by a trusted reverse proxy, when SSO is enabled.
+
+        Honored only when ``auth_proxy_header`` is configured, and only when the
+        value is a valid dns-1123 label — a spoofed or malformed value is never
+        trusted.
+        """
+        name = self.settings.auth_proxy_header
+        if not name:
+            return None
+        raw = (headers.get(name) or "").strip()
+        return raw if valid_user(raw) else None
+
     def _authorized(
         self,
         claim: dict,
         token: str | None,
         cookie_user: str | None,
         user: str,
+        remote: str | None = None,
     ) -> bool:
+        if remote == user:
+            return True  # identity asserted by the authenticating proxy
         if cookie_user is not None and cookie_user != user:
             return False  # a session for another user never authorizes this one
         return token_matches(claim, token)
 
+    async def _sso_session(
+        self, remote: str, headers, cookies, response: Response
+    ) -> dict | None:
+        """Provision ``remote`` idempotently and mint/refresh a session token.
+
+        The authenticating proxy has already verified ``remote``, so it is
+        trusted. A brand-new user is provisioned like ``signup`` (claim created,
+        token minted, sandbox awaited); an existing user whose session cookie is
+        missing or no longer matches gets a rotated token so a fresh cookie can
+        be issued. A still-valid session is reused untouched.
+        """
+        claim = await self.k8s.get_claim(remote)
+        token, cookie_user = self.credentials(headers, cookies)
+        if claim is not None and cookie_user == remote and token_matches(claim, token):
+            return claim
+        token = secrets.token_urlsafe(32)
+        token_hash = hashlib.sha256(token.encode()).hexdigest()
+        is_new = claim is None
+        if is_new:
+            try:
+                await self.k8s.create_claim(remote, token_hash, self.settings.pool)
+            except UserExists:
+                # Lost a concurrent signup race: rotate the existing token.
+                is_new = False
+                await self.k8s.patch_token(remote, token_hash)
+            else:
+                await self._touch(remote)
+                await self.wait_ready(remote, self.settings.wake_timeout)
+        else:
+            await self.k8s.patch_token(remote, token_hash)
+            await self._touch(remote)
+        self.set_session(response, remote, token)
+        return await self.k8s.get_claim(remote) if is_new else claim
+
     @staticmethod
     def _mutation_from_cookie(headers, method: str, cookie_user: str | None) -> bool:
         return (
@@ -767,7 +835,14 @@ class Gateway:
     async def healthz(self, request: Request) -> JSONResponse:
         return JSONResponse({"status": "ok"})
 
-    async def landing(self, request: Request) -> HTMLResponse:
+    async def landing(self, request: Request) -> Response:
+        remote = self.remote_user(request.headers)
+        if remote:
+            response = RedirectResponse(f"/u/{remote}/", status_code=303)
+            await self._sso_session(
+                remote, request.headers, request.cookies, response
+            )
+            return response
         token, user = self.credentials(request.headers, request.cookies)
         session = ""
         if user and token:
@@ -932,7 +1007,9 @@ against the JSON API. The browser session is an HttpOnly cookie.</p>
         if claim is None:
             return self._error(404, "not found")
         token, cookie_user = self.credentials(request.headers, request.cookies)
-        if not self._authorized(claim, token, cookie_user, user):
+        if not self._authorized(
+            claim, token, cookie_user, user, self.remote_user(request.headers)
+        ):
             return self._error(401, "unauthorized")
         sandbox = await self._sandbox_of(claim)
         return JSONResponse(
@@ -951,7 +1028,9 @@ against the JSON API. The browser session is an HttpOnly cookie.</p>
         if claim is None:
             return self._error(404, "not found")
         token, cookie_user = self.credentials(request.headers, request.cookies)
-        if not self._authorized(claim, token, cookie_user, user):
+        if not self._authorized(
+            claim, token, cookie_user, user, self.remote_user(request.headers)
+        ):
             return self._error(401, "unauthorized")
         if self._mutation_from_cookie(request.headers, "DELETE", cookie_user):
             return self._error(403, "cross-origin request rejected")
@@ -970,11 +1049,20 @@ against the JSON API. The browser session is an HttpOnly cookie.</p>
         user = request.path_params["user"]
         if not valid_user(user):
             return self._error(404, "unknown user")
+        remote = self.remote_user(request.headers)
         claim = await self.k8s.get_claim(user)
         if claim is None:
+            if remote == user:
+                # SSO first hit straight at a deep link: let landing bootstrap.
+                return RedirectResponse("/", status_code=303)
             return self._error(404, "unknown user")
         token, cookie_user = self.credentials(request.headers, request.cookies)
-        if not self._authorized(claim, token, cookie_user, user):
+        if remote == user and not (
+            cookie_user == user and token_matches(claim, token)
+        ):
+            # SSO user without a valid session cookie: bootstrap, then continue.
+            return RedirectResponse("/", status_code=303)
+        if not self._authorized(claim, token, cookie_user, user, remote):
             return self._error(401, "unauthorized")
         if self._mutation_from_cookie(request.headers, request.method, cookie_user):
             return self._error(403, "cross-origin request rejected")
@@ -1143,7 +1231,9 @@ against the JSON API. The browser session is an HttpOnly cookie.</p>
         if claim is None:
             return await self._ws_reject(websocket, 4401)
         token, cookie_user = self.credentials(websocket.headers, websocket.cookies)
-        if not self._authorized(claim, token, cookie_user, user):
+        if not self._authorized(
+            claim, token, cookie_user, user, self.remote_user(websocket.headers)
+        ):
             return await self._ws_reject(websocket, 4401)
         if cookie_user is not None and not same_origin(websocket.headers):
             return await self._ws_reject(websocket, 4401)

examples/dsh-agents-as-a-service/gateway/test_gateway.py

@@ -62,6 +62,7 @@ class FakeK8s:
         self.created = []
         self.deleted = []
         self.patches = []
+        self.token_patches = []
         self.conflict_on_create = False
         self.get_claim_error = None
         self.patch_error = None
@@ -92,6 +93,17 @@ class FakeK8s:
             raise self.patch_error
         self.patches.append((name, mode))
 
+    async def patch_token(self, user, token_hash):
+        if self.patch_error is not None:
+            raise self.patch_error
+        self.token_patches.append((user, token_hash))
+        claim = self.claims.get(user)
+        if claim is not None:
+            annotations = claim.setdefault("metadata", {}).setdefault(
+                "annotations", {}
+            )
+            annotations["aaas.example.com/token-sha256"] = token_hash
+
     async def get_pod(self, name):
         return self.pods.get(name)
 
@@ -431,6 +443,7 @@ def test_settings_from_env(monkeypatch):
     monkeypatch.setenv("COOKIE_MAX_AGE", "100")
     monkeypatch.setenv("MAX_BODY_MB", "2")
     monkeypatch.setenv("HTTP_TIMEOUT", "12.5")
+    monkeypatch.setenv("AUTH_PROXY_HEADER", "X-Forwarded-User")
     settings = Settings.from_env()
     assert settings.namespace == "ns-x"
     assert settings.pool == "pool-x"
@@ -443,6 +456,12 @@ def test_settings_from_env(monkeypatch):
     assert settings.cookie_max_age == 100
     assert settings.max_body_bytes == 2 * 1024 * 1024
     assert settings.http_timeout == 12.5
+    assert settings.auth_proxy_header == "X-Forwarded-User"
+
+
+def test_settings_auth_proxy_header_defaults_to_none(monkeypatch):
+    monkeypatch.delenv("AUTH_PROXY_HEADER", raising=False)
+    assert Settings.from_env().auth_proxy_header is None
 
 
 # --- Kubernetes adapter ----------------------------------------------------
@@ -1413,3 +1432,117 @@ async def test_sweeper_survives_transient_api_error(env):
 
     # The per-user maintenance flag must be released even on failure.
     assert env.gateway.state.maintenance["alice"] is False
+
+
+# --- SSO (reverse-proxy identity) ------------------------------------------
+
+
+def enable_sso(env, header="X-Forwarded-User"):
+    """Flip an env into SSO mode: the gateway trusts the named identity header."""
+    env.settings = Settings(**{**env.settings.__dict__, "auth_proxy_header": header})
+    env.gateway.settings = env.settings
+    return env
+
+
+def test_remote_user_none_when_sso_disabled(env):
+    assert env.gateway.remote_user({"X-Forwarded-User": "alice"}) is None
+
+
+def test_remote_user_returns_valid_and_rejects_invalid(env):
+    enable_sso(env)
+    g = env.gateway
+    assert g.remote_user({"X-Forwarded-User": "alice"}) == "alice"
+    assert g.remote_user({"X-Forwarded-User": "  bob "}) == "bob"
+    assert g.remote_user({"X-Forwarded-User": "UPPER"}) is None
+    assert g.remote_user({"X-Forwarded-User": "bad name"}) is None
+    assert g.remote_user({"X-Forwarded-User": ""}) is None
+    assert g.remote_user({}) is None
+
+
+@pytest.mark.asyncio
+async def test_sso_landing_provisions_new_user_and_redirects(env, monkeypatch):
+    enable_sso(env)
+
+    async def ready(user, timeout):
+        return {"metadata": {"name": f"dsh-{user}-sbx"}}
+
+    monkeypatch.setattr(env.gateway, "wait_ready", ready)
+    async with asgi_client(env) as client:
+        response = await client.get("/", headers={"X-Forwarded-User": "alice"})
+    assert response.status_code == 303
+    assert response.headers["location"] == "/u/alice/"
+    assert re_cookie_user(response.headers["set-cookie"]) == "alice"
+    assert [c[0] for c in env.k8s.created] == ["alice"]
+    assert env.k8s.token_patches == []
+
+
+@pytest.mark.asyncio
+async def test_sso_landing_reuses_valid_session_without_rotation(env):
+    enable_sso(env)
+    add_user(env.k8s)
+    async with asgi_client(
+        env, cookies={"dsh_gw_session": f"alice:{TOKEN}"}
+    ) as client:
+        response = await client.get("/", headers={"X-Forwarded-User": "alice"})
+    assert response.status_code == 303
+    assert response.headers["location"] == "/u/alice/"
+    assert env.k8s.created == []
+    assert env.k8s.token_patches == []
+
+
+@pytest.mark.asyncio
+async def test_sso_landing_rotates_token_when_session_missing(env):
+    enable_sso(env)
+    add_user(env.k8s)
+    async with asgi_client(env) as client:
+        response = await client.get("/", headers={"X-Forwarded-User": "alice"})
+    assert response.status_code == 303
+    assert response.headers["location"] == "/u/alice/"
+    assert re_cookie_user(response.headers["set-cookie"]) == "alice"
+    assert [p[0] for p in env.k8s.token_patches] == ["alice"]
+    assert env.k8s.created == []
+
+
+@pytest.mark.asyncio
+async def test_sso_get_user_authorizes_via_header(env):
+    enable_sso(env)
+    add_user(env.k8s)
+    async with asgi_client(env) as client:
+        response = await client.get(
+            "/users/alice", headers={"X-Forwarded-User": "alice"}
+        )
+    assert response.status_code == 200
+    assert response.json()["user"] == "alice"
+
+
+@pytest.mark.asyncio
+async def test_sso_proxy_redirects_to_bootstrap_without_session(env):
+    enable_sso(env)
+    add_user(env.k8s)
+    async with asgi_client(env) as client:
+        response = await client.get(
+            "/u/alice/", headers={"X-Forwarded-User": "alice"}
+        )
+    assert response.status_code == 303
+    assert response.headers["location"] == "/"
+
+
+@pytest.mark.asyncio
+async def test_sso_proxy_redirects_to_bootstrap_when_claim_missing(env):
+    enable_sso(env)
+    async with asgi_client(env) as client:
+        response = await client.get(
+            "/u/alice/", headers={"X-Forwarded-User": "alice"}
+        )
+    assert response.status_code == 303
+    assert response.headers["location"] == "/"
+
+
+@pytest.mark.asyncio
+async def test_spoofed_header_ignored_when_sso_disabled(env):
+    add_user(env.k8s)
+    async with asgi_client(env) as client:
+        response = await client.get(
+            "/u/alice/", headers={"X-Forwarded-User": "alice"}
+        )
+    assert response.status_code == 401

gateway-api/dsh-demo/README.md

@@ -1,21 +1,47 @@
-# Gateway API — external access for `dsh-demo/dsh-gateway`
+# Gateway API — external access for `dsh-demo/dsh-gateway` (GitHub SSO)
 
 Exposes the `dsh-gateway` service (`dsh-demo`, port `8080`) outside the cluster
-using the Kubernetes Gateway API (Traefik Gateway controller).
+using the Kubernetes Gateway API (Traefik Gateway controller), fronted by
+**oauth2-proxy** so access requires a GitHub login restricted to a configured
+GitHub organization. The gateway inherits the authenticated GitHub username via
+the `X-Forwarded-User` header (SSO).
+
+## Request flow
+
+```
+Browser ──▶ Gateway dsh-gateway (HTTPS, TLS-terminate)
+  ──▶ HTTPRoute <your-hostname>
+    ──▶ oauth2-proxy:4180   (GitHub OAuth, org-restricted)
+      ──▶ dsh-gateway:8080  (X-Forwarded-User = GitHub login → SSO)
+```
 
 ## Resources
 
 | File | Kind | Purpose |
 |---|---|---|
 | `gateway.yaml` | `Gateway` | HTTPS listener with TLS termination |
-| `httproute.yaml` | `HTTPRoute` | Routes the hostname → `dsh-gateway:8080` |
+| `httproute.yaml` | `HTTPRoute` | Routes the hostname → `oauth2-proxy:4180` |
+| `oauth2-proxy.yaml` | `Deployment`/`Service` | GitHub OAuth reverse proxy |
+| `oauth2-proxy-secret.yaml.example` | `Secret` | Example OAuth credentials (not applied as-is) |
 | `tls-secret.yaml.example` | `Secret` | Example TLS cert secret (not applied as-is) |
 
 ## Prerequisites
 
-1. **Hostname** — replace the placeholder in `httproute.yaml` with the real FQDN.
-2. **TLS secret** — create `dsh-demo-tls` in `dsh-demo` (see `tls-secret.yaml.example`).
-3. **Ingress and DNS** — configure the upstream ingress and public DNS for the hostname.
+1. **GitHub OAuth App** — create one at
+   `https://github.com/settings/developers` with:
+   - Homepage URL: `https://dsh-demo.example.com`
+   - Authorization callback URL: `https://dsh-demo.example.com/oauth2/callback`
+   (replace `dsh-demo.example.com` with the actual public FQDN). Note the client
+   ID and client secret.
+2. **oauth2-proxy Secret** — `kubectl -n dsh-demo create secret generic oauth2-proxy`
+   with `client-id`, `client-secret`, and a `cookie-secret`
+   (`openssl rand -base64 32`). See `oauth2-proxy-secret.yaml.example`.
+3. **TLS secret** — create `dsh-demo-tls` in `dsh-demo` (see `tls-secret.yaml.example`).
+4. **Gateway app env** — the `dsh-gateway` Deployment must run the SSO-capable
+   image with `AUTH_PROXY_HEADER=X-Forwarded-User` and `COOKIE_SECURE=true`
+   (see `examples/dsh-agents-as-a-service/50-gateway.yaml`).
+5. **Ingress and DNS** — configure the upstream ingress and public DNS for the
+   hostname.
 
 ## Apply
 
@@ -25,17 +51,24 @@ kubectl apply -f gateway-api/dsh-demo/ --dry-run=server
 kubectl apply -f gateway-api/dsh-demo/
 ```
 
-> ⚠️ A write-enabled kubeconfig is required to create Gateways and HTTPRoutes.
+> ⚠️ A write-enabled kubeconfig is required to create Gateways, HTTPRoutes,
+> Deployments, and Secrets.
 
 ## Verify
 
 ```bash
 kubectl get gateway dsh-gateway -n dsh-demo -o yaml        # expect Programmed=True
-kubectl get httproute -n dsh-demo -o wide             # expect Accepted
-kubectl get endpoints dsh-gateway -n dsh-demo         # backend present
-kubectl -n dsh-demo exec deploy/dsh-gateway -- wget -qO- http://localhost:8080/healthz
+kubectl get httproute -n dsh-demo -o wide                  # backend oauth2-proxy:4180, Accepted
+kubectl get deploy oauth2-proxy -n dsh-demo                # 1/1 Ready
+kubectl get endpoints oauth2-proxy -n dsh-demo             # backend present
+kubectl -n dsh-demo logs deploy/oauth2-proxy --tail=50     # no config errors
 ```
 
+Browser check: open `https://<your-hostname>/` — you should be redirected
+to GitHub, and after signing in as a member of the allowed organization your
+sandbox opens with the session showing your GitHub login. A non-member is denied
+before reaching the gateway.
+
 ## Rollback
 
 ```bash
@@ -44,6 +77,14 @@ kubectl delete -f gateway-api/dsh-demo/
 
 ## Notes
 
-- No `ReferenceGrant` is required: the Gateway, HTTPRoute, and backend Service are
-  all in `dsh-demo`.
-- The backend (`dsh-gateway`) serves plain HTTP on 8080 and has a `/healthz` probe.
+- **SSO is opt-in and additive.** The gateway honors `X-Forwarded-User` only when
+  `AUTH_PROXY_HEADER` is set; unset it to restore bearer-token/session-only auth.
+- **Trust boundary.** After this change the `dsh-gateway` Service must be reachable
+  **only** through oauth2-proxy (it is a ClusterIP Service). A second Route/Ingress
+  that exposes `dsh-gateway:8080` directly would let clients spoof the header.
+- **GitHub login → DSH user.** GitHub usernames are lowercase alphanumerics and
+  hyphens, so they map 1:1 onto the gateway's dns-1123 `user` validation.
+- **Sign-out.** The gateway `/logout` clears `dsh_gw_session`; oauth2-proxy's own
+  session can be cleared at `/oauth2/sign_out` if desired.
+- No `ReferenceGrant` is required: the Gateway, HTTPRoute, oauth2-proxy, and the
+  backend Service are all in `dsh-demo`.

gateway-api/dsh-demo/httproute.yaml

@@ -11,9 +11,11 @@ spec:
       namespace: dsh-demo
       sectionName: https
   hostnames:
-    # TODO: replace with the actual public FQDN once provided.
+    # TODO: replace with the actual public FQDN before applying.
     - dsh-demo.example.com
   rules:
     - backendRefs:
-        - name: dsh-gateway
-          port: 8080
+        # Route through oauth2-proxy (GitHub OAuth) first; it authenticates the
+        # browser and forwards to dsh-gateway:8080 with X-Forwarded-User set.
+        - name: oauth2-proxy
+          port: 4180

gateway-api/dsh-demo/oauth2-proxy-secret.yaml.example

@@ -0,0 +1,30 @@
+# EXAMPLE ONLY — do not apply as-is.
+#
+# oauth2-proxy reads its GitHub OAuth credentials and cookie-signing secret from
+# this Secret. Populate real values and apply:
+#
+#   kubectl -n dsh-demo create secret generic oauth2-proxy \
+#     --from-literal=client-id='<GitHub OAuth App client ID>' \
+#     --from-literal=client-secret='<GitHub OAuth App client secret>' \
+#     --from-literal=cookie-secret="$(openssl rand -base64 32)"
+#
+# The cookie secret must be a strong random value (16/24/32 bytes, base64).
+# Generate it with: openssl rand -base64 32
+#
+# GitHub OAuth App (https://github.com/settings/developers):
+#   Homepage URL            https://dsh-demo.example.com
+#   Authorization callback  https://dsh-demo.example.com/oauth2/callback
+#   (replace dsh-demo.example.com with the actual public FQDN)
+#
+# NOTE: the cookie secret should NOT be base64-encoded again when passed via
+# --from-literal (kubectl stores it as-is and the Secret encodes it for you).
+apiVersion: v1
+kind: Secret
+metadata:
+  name: oauth2-proxy
+  namespace: dsh-demo
+type: Opaque
+stringData:
+  client-id: "<github-oauth-app-client-id>"
+  client-secret: "<github-oauth-app-client-secret>"
+  cookie-secret: "<openssl-rand-base64-32>"

gateway-api/dsh-demo/oauth2-proxy.yaml

@@ -0,0 +1,119 @@
+# oauth2-proxy — GitHub OAuth login in front of the dsh-gateway.
+#
+# Runs as a reverse proxy: it authenticates the browser against GitHub
+# (restricted to a configured organization), then forwards the request to
+# the dsh-gateway Service with the authenticated identity in X-Forwarded-User
+# (plus X-Auth-Request-* via --set-xauthrequest). The gateway trusts that
+# header (AUTH_PROXY_HEADER) to inherit the username (SSO).
+#
+# Credentials come from the "oauth2-proxy" Secret (see
+# oauth2-proxy-secret.yaml.example); this manifest never carries secrets.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: oauth2-proxy
+  namespace: dsh-demo
+  labels:
+    app: oauth2-proxy
+    app.kubernetes.io/part-of: dsh-demo
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: oauth2-proxy
+  template:
+    metadata:
+      labels:
+        app: oauth2-proxy
+        app.kubernetes.io/part-of: dsh-demo
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 2000
+        runAsGroup: 2000
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: oauth2-proxy
+          image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5
+          imagePullPolicy: IfNotPresent
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          args:
+            - --http-address=0.0.0.0:4180
+            - --provider=github
+            # TODO: replace with the GitHub organization allowed to sign in.
+            - --github-org=your-github-org
+            - --email-domain=*
+            # Reverse-proxy target: the gateway backend Service.
+            - --upstream=http://dsh-gateway:8080
+            # Public callback (TLS terminates at the Gateway listener).
+            # TODO: replace with the actual public FQDN.
+            - --redirect-url=https://dsh-demo.example.com/oauth2/callback
+            - --cookie-secure=true
+            - --cookie-name=_oauth2_proxy
+            # Also expose X-Auth-Request-User/Email/Groups upstream.
+            - --set-xauthrequest
+            # Single provider: skip the provider-selection page.
+            - --skip-provider-button
+          env:
+            - name: OAUTH2_PROXY_CLIENT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: oauth2-proxy
+                  key: client-id
+            - name: OAUTH2_PROXY_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: oauth2-proxy
+                  key: client-secret
+            - name: OAUTH2_PROXY_COOKIE_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: oauth2-proxy
+                  key: cookie-secret
+          ports:
+            - name: http
+              containerPort: 4180
+          livenessProbe:
+            httpGet:
+              path: /ping
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 1
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /ready
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 3
+          resources:
+            requests:
+              cpu: 10m
+              memory: 32Mi
+            limits:
+              cpu: 200m
+              memory: 128Mi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: oauth2-proxy
+  namespace: dsh-demo
+  labels:
+    app: oauth2-proxy
+    app.kubernetes.io/part-of: dsh-demo
+spec:
+  selector:
+    app: oauth2-proxy
+  ports:
+    - name: http
+      port: 4180
+      targetPort: http