client secret bootstrapping

docs/REFERENCE.md

@@ -869,6 +869,65 @@ dind:
 - Gitea admin panel (`/admin/runners`) — runners show as Online
 - Create test workflow in `.gitea/workflows/test.yml` — job executes
 
+### Keycloak Secret Syncer
+
+**Type**: ArgoCD PostSync Job (deployed via Keycloak Helm chart `extraDeploy`)
+**Namespace**: `keycloak`
+
+**Purpose**: Automatically extracts Keycloak-generated client secrets and syncs them into Kubernetes Secrets in target namespaces. Eliminates the need to manually manage OIDC client secrets.
+
+**How It Works**:
+1. Runs as an ArgoCD PostSync hook after Keycloak resources are healthy
+2. Authenticates to Keycloak Admin API using admin credentials from `keycloak-credentials` secret
+3. Queries all clients in the `forte` realm
+4. Filters clients with `k8s.secret.sync: "true"` attribute
+5. For each matching client, retrieves the auto-generated secret via Keycloak Admin API
+6. Creates/updates a K8s Secret in the target namespace (from `k8s.secret.namespace` attribute)
+7. Always writes a central copy to the `secrets` namespace (for external deployment retrieval)
+
+**Resources**:
+- `ServiceAccount`: `keycloak-secret-syncer` (namespace: `keycloak`)
+- `ClusterRole`: `keycloak-secret-syncer` (secrets: get/create/update/patch; namespaces: get/list)
+- `ClusterRoleBinding`: `keycloak-secret-syncer`
+- `Job`: `keycloak-secret-syncer` (PostSync hook)
+
+**Client Attributes** (set in `forte-realm.json`):
+
+| Attribute | Description |
+|-----------|-------------|
+| `k8s.secret.sync` | Set to `"true"` to enable syncing |
+| `k8s.secret.namespace` | Target K8s namespace |
+| `k8s.secret.name` | Name of the K8s Secret |
+
+**Created Secret Format**:
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: <k8s.secret.name>
+  namespace: <k8s.secret.namespace>
+  labels:
+    app.kubernetes.io/managed-by: keycloak-secret-syncer
+type: Opaque
+data:
+  client-id: <base64-encoded client ID>
+  client-secret: <base64-encoded client secret>
+```
+
+**Verification**:
+```bash
+# Check job status
+kubectl get jobs -n keycloak
+
+# View syncer logs
+kubectl logs -n keycloak job/keycloak-secret-syncer
+
+# Verify created secret
+kubectl get secret <name> -n <namespace> -o yaml
+```
+
+**See**: [Developer Guide - Adding a New Keycloak Client](DEVELOPER-GUIDE.md#adding-a-new-keycloak-client)
+
 ### Renovate
 
 **Chart**: `renovate` (OCI: `ghcr.io/renovatebot/charts`)
@@ -1528,6 +1587,6 @@ team: platform
 
 ---
 
-**Last Updated**: 2026-04-14
+**Last Updated**: 2026-04-16
 **Maintained By**: Platform Team
 **Version**: 1.0.0