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>
2026-11-03 09:23:25 +00:00 · 2026-10-25 03:43:32 -03:00
parent 2b47afa22b
commit 3f46279b39
7 changed files with 445 additions and 23 deletions
--- a/gateway-api/dsh-demo/README.md
+++ b/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 gateway dsh-gateway -n dsh-demo -o yaml        # expect Programmed=True
+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`.
--- a/gateway-api/dsh-demo/httproute.yaml
+++ b/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
--- a/gateway-api/dsh-demo/oauth2-proxy-secret.yaml.example
+++ b/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>"
--- a/gateway-api/dsh-demo/oauth2-proxy.yaml
+++ b/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