From 87388712f087fe243f9f789db87a59d976db1f9e Mon Sep 17 00:00:00 2001 From: Keith Jackson Date: Thu, 27 Aug 2026 17:01:46 -0500 Subject: [PATCH] feat(gitea): wire native Keycloak OIDC SSO (break-glass admin retained) Wires the bootstrapping-critical Gitea git host to the Keycloak `homelab` realm as a native confidential OIDC client, moving it off the local-admin-only login while keeping the local admin as the break-glass path (docs/15 availability caveat; R-IDP-02/06). Realm (source of truth): add the `gitea` confidential client to platform/keycloak/keycloak-realm-import.yaml (modeled on grafana) + its GITEA_CLIENT_SECRET placeholder sourced from the keycloak-realm-clients Secret. NOTE: a KeycloakRealmImport no-ops on an already-existing realm, so the live client was ALSO created via kcadm (id 70a6ca60-317a-42ce-8331-a60e380838ee); the YAML keeps git authoritative for a rebuild. Secrets (SOPS/age, never plaintext): add gitea-client-secret to platform/keycloak/keycloak-realm-clients.sops.yaml (keycloak ns) and mirror the same value as oidc-client-secret into apps/wave-0/gitea-bootstrap-secret.sops.yaml (gitea ns) so the app can read it in-namespace. Both == the live client secret. App config (catalog source + re-render): catalog/gitea.yaml gains the GITEA_OIDC_CLIENT_SECRET env (from the mirrored Secret), [oauth2_client] auto-registration/account-linking app.ini env, and an idempotent postStart step that registers the "keycloak" OAuth2 login source (auto-discovery; groups claim; platform-admins -> Gitea admin). apps/wave-0/gitea.yaml re-rendered via `render.py --no-image-automation`. Verified: realm import Done=True/HasErrors=False and platform-config Ready=True/Healthy=True (unchanged); edited realm YAML passes server dry-run; static gate (lint/l0/l1) green. Browser SSO login still needs a human check. Co-Authored-By: Claude Opus 4.8 --- apps/wave-0/gitea-bootstrap-secret.sops.yaml | 5 +- apps/wave-0/gitea.yaml | 13 ++- catalog/gitea.yaml | 79 +++++++++++++++---- .../keycloak/keycloak-realm-clients.sops.yaml | 5 +- platform/keycloak/keycloak-realm-import.yaml | 37 +++++++++ 5 files changed, 118 insertions(+), 21 deletions(-) diff --git a/apps/wave-0/gitea-bootstrap-secret.sops.yaml b/apps/wave-0/gitea-bootstrap-secret.sops.yaml index 60182ce..bbda041 100644 --- a/apps/wave-0/gitea-bootstrap-secret.sops.yaml +++ b/apps/wave-0/gitea-bootstrap-secret.sops.yaml @@ -14,6 +14,7 @@ stringData: secret-key: ENC[AES256_GCM,data:N4wgSipwTYNgkwujPzGs8Bo63IzUip1TwfVq9fG+Z2nECrgIV9PYkEyL4ic3Ej9f5udOE4fHwsbgcyuiJw==,iv:p33bef3z2fDbaAi6beGF+CWmeTeS7Vn46ce1/2zQH4g=,tag:CLJ+kZbmz0tiPtOsI3+dIg==,type:str] admin-username: ENC[AES256_GCM,data:hyWYQ3UC8c9H2Os=,iv:bgn72bsILLxChY9QAsAD3tYWvsWS2CBe0FlneCCSr+E=,tag:7qP/P8TjDmRFsuXjJF8A2g==,type:str] admin-password: ENC[AES256_GCM,data:GPz1vracB1U6YurrV1AEhX9VEGx3lwCOXqOmKAg6+/6NjGPmTv+r2uosawVYtwie,iv:L/QKFqo7RpSg4eQGie/+R5BDBgTiTzwDdWuofJeebFE=,tag:cD6AU9tahLskTaaU/A7BOA==,type:str] + oidc-client-secret: ENC[AES256_GCM,data:T0CoSmS2yn0LBWdZ/AgkoMfNNoSTX+2EWzBMB3AV1ARxOP4mxP0IqElWvIH2xmseDJo7/o1fD0FU/E9BpgkSuw==,iv:xJoBSuBA6ATFd1XNVlI+tqj+hks1HvtAet3TGHtkxU8=,tag:h1P9pqubdvLk5znFLo/Slw==,type:str] sops: kms: [] gcp_kms: [] @@ -29,8 +30,8 @@ sops: Nys4V2NBZWF6U2lER05HV3FNZ1pOQ1kKEVHBTPTAJfiQBzkP/QezTzOfS96nYzxg Ad1m50j67vyFaBCVAb0/0toEUAm+qEV4wzOglaNmZuScavY4ntwCIw== -----END AGE ENCRYPTED FILE----- - lastmodified: "2026-08-25T23:06:33Z" - mac: ENC[AES256_GCM,data:ik735BfSMdlB4IUceScEfY4aNNNo61po7W7x/6iod1VvsiMo0+7nUrVqD2uiL8p066k6g/hV+BNg5BwnYRVjvkVm8tU60ctcjEDfinxtgnqRNBVK81RROn5GtsRCzuBxiJ5J8ulgb45+jG9ND6Xuo9XuTZ35PWs/4/Ebdl/jpPM=,iv:Nt3QtDz3S37AnrtG2nd1TIHgFFemgxXrKrHfXTVo6S4=,tag:ScMtwQAF8a4heyhN+iXt/A==,type:str] + lastmodified: "2026-08-27T21:58:13Z" + mac: ENC[AES256_GCM,data:/4DR4Ot6ZBeCoe9zJQoAV/WqmAx1TvsNbYbwpDhqDETGJkatIkbo5VivwljeocZsuWVKklefNZE95ycFzN+fAVsZoY03n4B7fdp4KpjoSFRs9IhhJYM57vamWDP0ppjhGzOV5RoT8kynZiIvBCXJjhs072ilwpQ8qLdTCmMMgbU=,iv:m9M2vJIqlTS4vWBEzLwtr7G8IrTFSHQuh5eAjdyUx8s=,tag:VF9jnwHWemowIC2pWS2AwQ==,type:str] pgp: [] encrypted_regex: ^(data|stringData)$ version: 3.9.4 diff --git a/apps/wave-0/gitea.yaml b/apps/wave-0/gitea.yaml index d85a72b..c3665f8 100644 --- a/apps/wave-0/gitea.yaml +++ b/apps/wave-0/gitea.yaml @@ -107,6 +107,17 @@ spec: secretKeyRef: name: gitea-bootstrap key: admin-password + - name: GITEA_OIDC_CLIENT_SECRET + valueFrom: + secretKeyRef: + name: gitea-bootstrap + key: oidc-client-secret + - name: GITEA__oauth2_client__ENABLE_AUTO_REGISTRATION + value: 'true' + - name: GITEA__oauth2_client__ACCOUNT_LINKING + value: auto + - name: GITEA__oauth2_client__USERNAME + value: preferred_username volumeMounts: - name: data mountPath: /data @@ -116,7 +127,7 @@ spec: command: - /bin/sh - -c - - "# Idempotent break-glass admin bootstrap. Runs alongside the gitea entrypoint\n# (which, with INSTALL_LOCK=true, headless-installs + migrates the DB on first\n# boot). Waits for the DB, then creates the admin only if it does not exist.\nset -u\nexport HOME=/data/git\ni=0\nuntil su-exec git gitea admin user list >/dev/null 2>&1; do\n i=$((i + 1))\n [ \"$i\" -ge 150 ] && { echo \"[gitea-bootstrap] DB not ready after wait; skipping\" >&2; exit 0; }\n sleep 2\ndone\nif su-exec git gitea admin user list --admin 2>/dev/null | awk 'NR>1{print $2}' | grep -qx \"$GITEA_ADMIN_USERNAME\"; then\n echo \"[gitea-bootstrap] admin '$GITEA_ADMIN_USERNAME' already present\"\n exit 0\nfi\nn=0\nuntil su-exec git gitea admin user create \\\n --username \"$GITEA_ADMIN_USERNAME\" \\\n --password \"$GITEA_ADMIN_PASSWORD\" \\\n --email \"$GITEA_ADMIN_USERNAME@home.local\" \\\n --admin --must-change-password=false; do\n n=$((n + 1))\n [ \"$n\" -ge 10 ] && { echo \"[gitea-bootstrap] admin create failed after retries\" >&2; exit 0; }\n sleep 3\ndone\necho \"[gitea-bootstrap] created break-glass admin '$GITEA_ADMIN_USERNAME'\"\n" + - "# Idempotent break-glass admin bootstrap. Runs alongside the gitea entrypoint\n# (which, with INSTALL_LOCK=true, headless-installs + migrates the DB on first\n# boot). Waits for the DB, then creates the admin only if it does not exist.\nset -u\nexport HOME=/data/git\ni=0\nuntil su-exec git gitea admin user list >/dev/null 2>&1; do\n i=$((i + 1))\n [ \"$i\" -ge 150 ] && { echo \"[gitea-bootstrap] DB not ready after wait; skipping\" >&2; exit 0; }\n sleep 2\ndone\nif su-exec git gitea admin user list --admin 2>/dev/null | awk 'NR>1{print $2}' | grep -qx \"$GITEA_ADMIN_USERNAME\"; then\n echo \"[gitea-bootstrap] admin '$GITEA_ADMIN_USERNAME' already present\"\nelse\n n=0\n until su-exec git gitea admin user create \\\n --username \"$GITEA_ADMIN_USERNAME\" \\\n --password \"$GITEA_ADMIN_PASSWORD\" \\\n --email \"$GITEA_ADMIN_USERNAME@home.local\" \\\n --admin --must-change-password=false; do\n n=$((n + 1))\n [ \"$n\" -ge 10 ] && { echo \"[gitea-bootstrap] admin create failed after retries\" >&2; break; }\n sleep 3\n done\n echo \"[gitea-bootstrap] created break-glass admin '$GITEA_ADMIN_USERNAME'\"\nfi\n# --- Keycloak OIDC login source (idempotent add-or-update; R-IDP-02/06) ---\n# Registers the confidential `gitea` client as the OAuth2 login source \"keycloak\" against the\n# homelab realm's discovery doc. The `groups` claim maps the platform-admins group to Gitea\n# admin (--admin-group). Auto-discovery pulls auth/token/userinfo/jwks endpoints. Runs on every\n# start: updates the existing source if present, else creates it. Missing secret => skip (the\n# local break-glass admin above still works), so an unfilled secret never crashes the pod.\nif [ -n \"${GITEA_OIDC_CLIENT_SECRET:-}\" ]; then\n oidc_id=$(su-exec git gitea admin auth list 2>/dev/null | awk '$2==\"keycloak\"{print $1; exit}')\n if [ -n \"$oidc_id\" ]; then\n su-exec git gitea admin auth update-oauth --id \"$oidc_id\" \\\n --name keycloak --provider openidConnect --key gitea \\\n --secret \"$GITEA_OIDC_CLIENT_SECRET\" \\\n --auto-discover-url https://keycloak.home.keithjackson.dev/realms/homelab/.well-known/openid-configuration \\\n --scopes \"openid email profile\" --group-claim-name groups --admin-group platform-admins \\\n && echo \"[gitea-oidc] updated login source 'keycloak' (id $oidc_id)\" \\\n || echo \"[gitea-oidc] update-oauth failed\" >&2\n else\n su-exec git gitea admin auth add-oauth \\\n --name keycloak --provider openidConnect --key gitea \\\n --secret \"$GITEA_OIDC_CLIENT_SECRET\" \\\n --auto-discover-url https://keycloak.home.keithjackson.dev/realms/homelab/.well-known/openid-configuration \\\n --scopes \"openid email profile\" --group-claim-name groups --admin-group platform-admins \\\n && echo \"[gitea-oidc] added login source 'keycloak'\" \\\n || echo \"[gitea-oidc] add-oauth failed\" >&2\n fi\nelse\n echo \"[gitea-oidc] GITEA_OIDC_CLIENT_SECRET unset; skipping OIDC source (break-glass admin only)\"\nfi\n" volumes: - name: data persistentVolumeClaim: diff --git a/catalog/gitea.yaml b/catalog/gitea.yaml index df9132b..7fd7382 100644 --- a/catalog/gitea.yaml +++ b/catalog/gitea.yaml @@ -41,6 +41,23 @@ env: secretKeyRef: name: gitea-bootstrap key: admin-password + # --- Keycloak native OIDC SSO (auth.mode oidc; docs/15 "Native OIDC"; R-IDP-02/06). The confidential + # `gitea` realm client's secret is mirrored into this namespace's gitea-bootstrap Secret (the same + # value SOPS-held in keycloak-realm-clients); the postStart hook registers it as the "keycloak" + # OAuth2 login source. The LOCAL admin above stays as the break-glass path (docs/15). --- + - name: GITEA_OIDC_CLIENT_SECRET + valueFrom: + secretKeyRef: + name: gitea-bootstrap + key: oidc-client-secret + # app.ini [oauth2_client]: auto-provision a Gitea account on first Keycloak login and link it to an + # existing local account by verified email, so SSO users don't need a pre-created local user. + - name: GITEA__oauth2_client__ENABLE_AUTO_REGISTRATION + value: "true" + - name: GITEA__oauth2_client__ACCOUNT_LINKING + value: auto + - name: GITEA__oauth2_client__USERNAME + value: preferred_username lifecycle: postStart: exec: @@ -61,19 +78,47 @@ lifecycle: done if su-exec git gitea admin user list --admin 2>/dev/null | awk 'NR>1{print $2}' | grep -qx "$GITEA_ADMIN_USERNAME"; then echo "[gitea-bootstrap] admin '$GITEA_ADMIN_USERNAME' already present" - exit 0 + else + n=0 + until su-exec git gitea admin user create \ + --username "$GITEA_ADMIN_USERNAME" \ + --password "$GITEA_ADMIN_PASSWORD" \ + --email "$GITEA_ADMIN_USERNAME@home.local" \ + --admin --must-change-password=false; do + n=$((n + 1)) + [ "$n" -ge 10 ] && { echo "[gitea-bootstrap] admin create failed after retries" >&2; break; } + sleep 3 + done + echo "[gitea-bootstrap] created break-glass admin '$GITEA_ADMIN_USERNAME'" + fi + # --- Keycloak OIDC login source (idempotent add-or-update; R-IDP-02/06) --- + # Registers the confidential `gitea` client as the OAuth2 login source "keycloak" against the + # homelab realm's discovery doc. The `groups` claim maps the platform-admins group to Gitea + # admin (--admin-group). Auto-discovery pulls auth/token/userinfo/jwks endpoints. Runs on every + # start: updates the existing source if present, else creates it. Missing secret => skip (the + # local break-glass admin above still works), so an unfilled secret never crashes the pod. + if [ -n "${GITEA_OIDC_CLIENT_SECRET:-}" ]; then + oidc_id=$(su-exec git gitea admin auth list 2>/dev/null | awk '$2=="keycloak"{print $1; exit}') + if [ -n "$oidc_id" ]; then + su-exec git gitea admin auth update-oauth --id "$oidc_id" \ + --name keycloak --provider openidConnect --key gitea \ + --secret "$GITEA_OIDC_CLIENT_SECRET" \ + --auto-discover-url https://keycloak.home.keithjackson.dev/realms/homelab/.well-known/openid-configuration \ + --scopes "openid email profile" --group-claim-name groups --admin-group platform-admins \ + && echo "[gitea-oidc] updated login source 'keycloak' (id $oidc_id)" \ + || echo "[gitea-oidc] update-oauth failed" >&2 + else + su-exec git gitea admin auth add-oauth \ + --name keycloak --provider openidConnect --key gitea \ + --secret "$GITEA_OIDC_CLIENT_SECRET" \ + --auto-discover-url https://keycloak.home.keithjackson.dev/realms/homelab/.well-known/openid-configuration \ + --scopes "openid email profile" --group-claim-name groups --admin-group platform-admins \ + && echo "[gitea-oidc] added login source 'keycloak'" \ + || echo "[gitea-oidc] add-oauth failed" >&2 + fi + else + echo "[gitea-oidc] GITEA_OIDC_CLIENT_SECRET unset; skipping OIDC source (break-glass admin only)" fi - n=0 - until su-exec git gitea admin user create \ - --username "$GITEA_ADMIN_USERNAME" \ - --password "$GITEA_ADMIN_PASSWORD" \ - --email "$GITEA_ADMIN_USERNAME@home.local" \ - --admin --must-change-password=false; do - n=$((n + 1)) - [ "$n" -ge 10 ] && { echo "[gitea-bootstrap] admin create failed after retries" >&2; exit 0; } - sleep 3 - done - echo "[gitea-bootstrap] created break-glass admin '$GITEA_ADMIN_USERNAME'" exposure: public # edge-forwarded git host at gitea.home.keithjackson.dev (docs/09; R-DNS/R-NET) egress: internet # normal WAN egress (docs/03; R-NET-05) storage: @@ -90,10 +135,12 @@ auth: mode: oidc # native Keycloak OIDC client (docs/13 SSO row, docs/15 "Native OIDC" set; R-IDP-02) groups: - platform-admins # access scoped to an authorized group (R-IDP-06) - # NOTE (OIDC follow-up + break-glass): Gitea keeps a LOCAL admin as the break-glass path so an IdP - # outage never locks the operator out of recovery tools (docs/15 "Availability caveat"). At initial - # deploy Gitea comes up on that local admin; the Keycloak OIDC client (+ SOPS client secret) is wired - # once Keycloak is live. This declaration records the target integration; it does not embed a secret. + # WIRED (native OIDC): the Keycloak `gitea` confidential client (platform/keycloak/keycloak-realm- + # import.yaml + live kcadm) is registered as Gitea's "keycloak" OAuth2 login source by the postStart + # hook, using the client secret mirrored into the gitea-bootstrap Secret (oidc-client-secret; same + # value SOPS-held in keycloak-realm-clients). platform-admins (groups claim) -> Gitea admin. Gitea + # KEEPS a LOCAL admin as the break-glass path so an IdP outage never locks the operator out of + # recovery tools (docs/15 "Availability caveat"). No secret is embedded here. update: channel: stable # R-UPD-01 range: ">=1.22.0 <2.0.0" # stay on the 1.x stable line diff --git a/platform/keycloak/keycloak-realm-clients.sops.yaml b/platform/keycloak/keycloak-realm-clients.sops.yaml index 5dce5df..aed9d13 100644 --- a/platform/keycloak/keycloak-realm-clients.sops.yaml +++ b/platform/keycloak/keycloak-realm-clients.sops.yaml @@ -7,6 +7,7 @@ type: Opaque stringData: grafana-client-secret: ENC[AES256_GCM,data:J6grYrkJVubGNS+z1WrcUuvjKu2Z/fETWNXsKkjQnk/RlitaMjDqkazglKgy8PkEymNLNuVao48gksnuNLQ6aA==,iv:9sw5IdW+7GuwsRjn4NSi2JVZh9mTE2hiWJQYQS7w2bA=,tag:2hOUFeFqcQJsPeC8e6U4RA==,type:str] oauth2-proxy-client-secret: ENC[AES256_GCM,data:hE9mN6A6uTL3GpqOCGb3T0qVR9bcY4wcqNlgcrs9+uezSeci/Vs9uiXeFzfD57klHe8nEqxF1bCftD0GVFadhQ==,iv:rP2CbbGG4LWmGyV0adrlsmn2GtQLH8hSlqbioOAD824=,tag:p28vfuSZxYMs7XnAjslBWg==,type:str] + gitea-client-secret: ENC[AES256_GCM,data:ObU5sWSq2xEZKgqwccFo/kzs/nfhOVJ0NceBlgxgy6a6iOWeUN079iQpJ0ADoJyjsoQk1IQediFD06rwVSvNIQ==,iv:Bc4L8MngA6YKNRQRwEQojnUo5ixdS2t1AocvGMwE0oQ=,tag:YsozaKtL6CR68sPmGiL5wA==,type:str] sops: kms: [] gcp_kms: [] @@ -22,8 +23,8 @@ sops: YXJGUUJiTnFndFhDZDU1bmxXTENCbmsKuhb3RQ3LZmuTPAXEck8b6iuZ5vxLb9fV +fQELmU4kOTbZrPSxy+kpttLG5Cy5d6X2ieZXBf6opzpLTUhlBOkHA== -----END AGE ENCRYPTED FILE----- - lastmodified: "2026-08-25T03:06:30Z" - mac: ENC[AES256_GCM,data:wJ6Mf7yFXnnnuo/IhfGdDYcgNUzzNv2bFGN6wPwmVRr1To4rt3DGb1JZO19OxvloWYrGAyJaeXzC5NCLGDZOzS99TBmMy1TIeEYUqd6zEmFofEla0mZyLFGLsU/JUIVL3d1l4ECPmcHpUnEjJf4o4kE8BxkWAyHSMWktB69a1cc=,iv:7E7T7cFpAcT42ryTfqbDUoWr0d23a9rCI3n//LgBFS8=,tag:zVXOh/hjQNousg85TZw/Zg==,type:str] + lastmodified: "2026-08-27T21:58:13Z" + mac: ENC[AES256_GCM,data:+QNCSmJMoAAUibsQZ7by/Neno6VfxLoxCNUoRwHAW+T3SDrgQI7hkrVcWr39bpCne7AAGnlyVS7Zd4m3lk/ZGs90LbSx5xdFyGPQ7vpI774aaIMQJe+84pBPLGw1NH8bVmDOS99P0rlIG0lGBixl4UqrQ3BWhgnd63tAvnKnCBU=,iv:K4Wi+LvKhszj3bnRBuheHdbS2UwhlN6hBJP/H3nEo9M=,tag:P4+14EaB88QQNzDvCUlnJA==,type:str] pgp: [] encrypted_regex: ^(data|stringData)$ version: 3.9.4 diff --git a/platform/keycloak/keycloak-realm-import.yaml b/platform/keycloak/keycloak-realm-import.yaml index 2b55896..96a4192 100644 --- a/platform/keycloak/keycloak-realm-import.yaml +++ b/platform/keycloak/keycloak-realm-import.yaml @@ -23,6 +23,10 @@ spec: secret: name: keycloak-realm-clients key: oauth2-proxy-client-secret + GITEA_CLIENT_SECRET: + secret: + name: keycloak-realm-clients + key: gitea-client-secret realm: realm: homelab enabled: true @@ -145,6 +149,39 @@ spec: "access.token.claim": "true" "userinfo.token.claim": "true" "claim.name": groups + # gitea — native OIDC SSO for the bootstrapping-critical git host (catalog/gitea.yaml auth.mode + # oidc; docs/13 SSO row, docs/15 "Native OIDC"; R-IDP-02). Confidential auth-code client modeled on + # grafana. Redirect URI is Gitea's OAuth2 callback for the auth source named `keycloak` + # (/user/oauth2//callback). The `groups` claim drives authorization: Gitea maps the + # platform-admins group -> Gitea admin (auth source --admin-group; R-IDP-06). The LOCAL Gitea admin + # remains the break-glass path (docs/15 availability caveat). Secret injected from the SOPS + # keycloak-realm-clients Secret via the GITEA_CLIENT_SECRET placeholder (R-IDP-04). + - clientId: gitea + name: Gitea + protocol: openid-connect + enabled: true + publicClient: false + standardFlowEnabled: true + directAccessGrantsEnabled: false + secret: "$(env:GITEA_CLIENT_SECRET)" + redirectUris: + - https://gitea.home.keithjackson.dev/user/oauth2/keycloak/callback + webOrigins: + - https://gitea.home.keithjackson.dev + defaultClientScopes: + - email + - profile + - roles + protocolMappers: + - name: groups + protocol: openid-connect + protocolMapper: oidc-group-membership-mapper + config: + "full.path": "false" + "id.token.claim": "true" + "access.token.claim": "true" + "userinfo.token.claim": "true" + "claim.name": groups # --- MFA for platform-admins (R-IDP-04): a browser flow whose OTP step is CONDITIONAL on the # platform-admin role. Non-admins log in without OTP; platform-admins must enroll/present TOTP. # Set as the realm browserFlow below. VERIFY at bring-up (see runbook): a malformed flow fails