feat(nextcloud,semaphore): wire native Keycloak OIDC SSO (break-glass admins retained)

Extends the SSO work to the two remaining `auth: oidc` apps still on local-admin
logins, each as a native confidential client of the Keycloak `homelab` realm with
its local admin kept as break-glass (docs/15 availability caveat; R-IDP-02/06).

Realm (source of truth): add the `nextcloud` and `semaphore` confidential clients
to platform/keycloak/keycloak-realm-import.yaml (modeled on grafana/gitea) + their
NEXTCLOUD_CLIENT_SECRET / SEMAPHORE_CLIENT_SECRET placeholders. As before, a
KeycloakRealmImport no-ops on an already-existing realm, so both live clients were
ALSO created via kcadm (nextcloud e95049ed-ca10-4085-97d9-4bbef495fe61, semaphore
1835bfe9-b125-4026-8f69-33557519cf4a); the YAML keeps git authoritative.

Secrets (SOPS/age): add nextcloud-client-secret + semaphore-client-secret to
keycloak-realm-clients.sops.yaml (keycloak ns). Mirror the nextcloud secret as
oidc-client-secret into nextcloud-bootstrap (nextcloud ns). For semaphore, the
whole SEMAPHORE_OIDC_PROVIDERS JSON (which embeds the client secret) is held
encrypted as oidc-providers-json in semaphore-bootstrap (semaphore ns). All values
verified == the live clients; existing keys untouched; no plaintext in git.

App config (catalog source + re-render):
- nextcloud: add NEXTCLOUD_OIDC_CLIENT_SECRET env + an idempotent postStart hook
  that installs/enables user_oidc and runs `occ user_oidc:provider keycloak`
  (create-or-update; secret via --clientsecret-env so it never hits argv; occ as
  www-data; group provisioning on the `groups` claim). Syntax verified against the
  running user_oidc 8.11.0 on Nextcloud 31.0.14; su-to-www-data env passthrough
  verified. Missing-secret/not-installed guards prevent crashloops.
- semaphore: add SEMAPHORE_OIDC_PROVIDERS env sourced from the encrypted
  oidc-providers-json (provider_url=realm issuer/auto-discovery, redirect
  /api/auth/oidc/keycloak/redirect). Mechanism verified against semaphore v2.19.10
  source (util ConfigType oidc_providers env tag + OidcProvider struct + router
  redirect path); no kubelet service-link env collision.
apps/wave-1/{nextcloud,semaphore}.yaml re-rendered via
`render.py --no-image-automation` (diffs are env/lifecycle-only).

Verified: realm import Done=True/HasErrors=False and platform-config
Ready=True/Healthy=True (unchanged); edited realm YAML passes server dry-run; live
homelab clients now include gitea/nextcloud/semaphore; static gate (lint/l0/l1)
green. Browser SSO login for each still needs a human check.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

catalog/nextcloud.yaml

@@ -57,6 +57,62 @@ env:
     value: https
   - name: OVERWRITECLIURL
     value: https://nextcloud.home.keithjackson.dev
+  # --- Keycloak native OIDC SSO (auth.mode oidc; docs/15 "Native OIDC"; R-IDP-02/06). The confidential
+  #     `nextcloud` realm client's secret is mirrored into this namespace's nextcloud-bootstrap Secret
+  #     (oidc-client-secret; same value SOPS-held in keycloak-realm-clients). The postStart hook reads it
+  #     via user_oidc's --clientsecret-env (never on argv) to register the "keycloak" provider. The LOCAL
+  #     admin above stays as the break-glass path (docs/15). ---
+  - name: NEXTCLOUD_OIDC_CLIENT_SECRET
+    valueFrom:
+      secretKeyRef:
+        name: nextcloud-bootstrap
+        key: oidc-client-secret
+lifecycle:
+  postStart:
+    exec:
+      command:
+        - /bin/sh
+        - -c
+        - |
+          # Idempotent Keycloak OIDC wiring (R-IDP-02/06). Runs alongside the nextcloud entrypoint
+          # (which installs/upgrades on first boot). Installs+enables the user_oidc app and creates OR
+          # updates the "keycloak" login provider (occ user_oidc:provider is create-or-update by
+          # identifier). Auto-discovery pulls the realm's endpoints; the `groups` claim drives Nextcloud
+          # group provisioning. occ runs as www-data (owns config.php); the client secret is passed via
+          # --clientsecret-env so it never lands on a command line. Safe to re-run every start; a missing
+          # secret or not-yet-installed instance is skipped so the pod never crashloops (the local
+          # break-glass admin still works).
+          set -u
+          OCC() { su -s /bin/sh www-data -c "php /var/www/html/occ $*"; }
+          i=0
+          until OCC status 2>/dev/null | grep -q "installed: true"; do
+            i=$((i + 1))
+            [ "$i" -ge 300 ] && { echo "[nextcloud-oidc] occ not ready after wait; skipping" >&2; exit 0; }
+            sleep 2
+          done
+          if [ -z "${NEXTCLOUD_OIDC_CLIENT_SECRET:-}" ]; then
+            echo "[nextcloud-oidc] client secret unset; skipping OIDC (break-glass admin only)"
+            exit 0
+          fi
+          if ! OCC app:list 2>/dev/null | grep -q "user_oidc"; then
+            OCC app:install user_oidc || echo "[nextcloud-oidc] app:install user_oidc failed" >&2
+          fi
+          OCC app:enable user_oidc >/dev/null 2>&1 || true
+          if OCC user_oidc:provider keycloak \
+            --clientid=nextcloud \
+            --clientsecret-env=NEXTCLOUD_OIDC_CLIENT_SECRET \
+            --discoveryuri=https://keycloak.home.keithjackson.dev/realms/homelab/.well-known/openid-configuration \
+            --scope="openid email profile" \
+            --unique-uid=0 \
+            --mapping-uid=preferred_username \
+            --mapping-email=email \
+            --mapping-display-name=name \
+            --group-provisioning=1 \
+            --mapping-groups=groups; then
+            echo "[nextcloud-oidc] provider 'keycloak' configured"
+          else
+            echo "[nextcloud-oidc] provider config failed" >&2
+          fi
 exposure: public                # edge port-forward + public DNS (docs/09; R-DNS/R-NET)
 egress: internet                # normal WAN egress (docs/03; R-NET-05) — app store, integrity checks
 storage:
@@ -77,14 +133,12 @@ auth:
   mode: oidc                    # native Keycloak OIDC client (docs/13 SSO row, docs/15 "Native OIDC"; R-IDP-02)
   groups:
     - platform-admins           # access scoped to an authorized group (R-IDP-06)
-  # NOTE (OIDC follow-up + break-glass): like Gitea (docs/15 "Availability caveat"), Nextcloud keeps a
-  # LOCAL admin as the break-glass path so an IdP outage never locks the operator out. At initial deploy
-  # it comes up INSTALLED on that local admin (env above). The Keycloak `nextcloud` realm client + its
-  # user_oidc app config is a DEFERRED follow-up: wiring it means editing the reconciled realm import in
-  # platform-config (a malformed edit fails the whole platform-config apply / can leave the realm import
-  # PENDING) AND post-install `occ` steps the image has no first-class env for — deferred rather than
-  # risking the running Keycloak realm / Flux source (WS-APPS step 3 escape hatch). This records the
-  # target integration; it embeds no secret.
+  # WIRED (native OIDC): the Keycloak `nextcloud` confidential client (platform/keycloak/keycloak-realm-
+  # import.yaml + live kcadm) is registered as a user_oidc login provider ("keycloak") by the postStart
+  # hook (occ user_oidc:provider), using the client secret mirrored into nextcloud-bootstrap
+  # (oidc-client-secret; same value SOPS-held in keycloak-realm-clients). The `groups` claim drives
+  # user_oidc group provisioning (R-IDP-06). Nextcloud KEEPS its LOCAL admin as the break-glass path so
+  # an IdP outage never locks the operator out (docs/15 "Availability caveat"). No secret is embedded here.
 update:
   channel: stable               # R-UPD-01
   range: ">=31.0.0 <32.0.0"     # stay on the 31.x stable line