client secret bootstrapping

docs/DEVELOPER-GUIDE.md

@@ -9,6 +9,7 @@
 - [Updating an Existing Application](#updating-an-existing-application)
 - [Working with Secrets](#working-with-secrets)
 - [Enabling Authentication for Applications](#enabling-authentication-for-applications)
+- [Adding a New Keycloak Client](#adding-a-new-keycloak-client)
 - [Troubleshooting](#troubleshooting)
 - [Best Practices](#best-practices)
 
@@ -1247,6 +1248,135 @@ kubectl logs -n myapp <pod-name> -c authn
 
 ---
 
+## Adding a New Keycloak Client
+
+When you need an application to authenticate via Keycloak (OIDC), you can add a client definition to the realm config. The secret syncer automatically extracts the Keycloak-generated client secret into a Kubernetes Secret that your application can reference — no manual secret management needed.
+
+### How It Works
+
+1. You define a client in `forte-realm.json` (inside `keycloak-values.yaml`) **without** a `secret` field
+2. Keycloak auto-generates a cryptographically strong secret on first creation
+3. An ArgoCD **PostSync Job** (`keycloak-secret-syncer`) runs after each Keycloak sync:
+   - Authenticates to the Keycloak Admin API
+   - Finds clients with `k8s.secret.sync: "true"` in their attributes
+   - Extracts the auto-generated secret for each client
+   - Creates/updates a K8s Secret in the target namespace with `client-id` and `client-secret` keys
+4. Your application references the syncer-created Secret
+
+### Step 1: Add Client to Realm Config
+
+In `infra/values/keycloak-values.yaml`, add a new entry to the `clients` array in `forte-realm.json`:
+
+```json
+{
+  "clientId": "myapp",
+  "name": "My Application",
+  "enabled": true,
+  "protocol": "openid-connect",
+  "clientAuthenticatorType": "client-secret",
+  "standardFlowEnabled": true,
+  "directAccessGrantsEnabled": false,
+  "publicClient": false,
+  "redirectUris": ["https://myapp.forteapps.net/*"],
+  "webOrigins": ["https://myapp.forteapps.net"],
+  "defaultClientScopes": ["openid", "email", "profile"],
+  "attributes": {
+    "k8s.secret.sync": "true",
+    "k8s.secret.namespace": "myapp",
+    "k8s.secret.name": "myapp-oidc-credentials"
+  }
+}
+```
+
+**Important**:
+- Do **NOT** include a `"secret"` field — Keycloak generates one automatically
+- The `attributes` block tells the syncer where to create the K8s Secret
+- The target namespace must exist before the syncer runs (ArgoCD creates it via `CreateNamespace=true`)
+
+### Step 2: Reference the Secret in Your Application
+
+In your application's Helm values, reference the syncer-created secret:
+
+```yaml
+# In helm-values/myapp/values.yaml (or inline in values file)
+# The secret will have keys: client-id, client-secret
+existingSecret: myapp-oidc-credentials
+key: client-secret
+```
+
+For Gitea-style oauth config:
+```yaml
+oauth:
+- name: "Forte"
+  provider: "openidConnect"
+  existingSecret: myapp-oidc-credentials
+  key: client-secret
+  autoDiscoverUrl: "https://id.forteapps.net/realms/forte/.well-known/openid-configuration"
+```
+
+### Step 3: Commit and Push
+
+```bash
+cd ~/dev/k8s/launchpad
+git add infra/values/keycloak-values.yaml
+git commit -m "Add myapp Keycloak client with auto-sync"
+git push
+```
+
+ArgoCD will:
+1. Sync the Keycloak config (keycloakConfigCli creates the client)
+2. Run the PostSync syncer Job
+3. The syncer creates `myapp-oidc-credentials` in the `myapp` namespace
+
+### Step 4: Verify
+
+```bash
+# Check the syncer job ran successfully
+kubectl get jobs -n keycloak
+kubectl logs -n keycloak job/keycloak-secret-syncer
+
+# Verify the secret was created
+kubectl get secret myapp-oidc-credentials -n myapp -o yaml
+
+# Check the secret has the expected keys
+kubectl get secret myapp-oidc-credentials -n myapp -o jsonpath='{.data.client-id}' | base64 -d
+kubectl get secret myapp-oidc-credentials -n myapp -o jsonpath='{.data.client-secret}' | base64 -d
+```
+
+### Sync Attribute Reference
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `k8s.secret.sync` | Yes | Set to `"true"` to enable syncing |
+| `k8s.secret.namespace` | Yes | Target K8s namespace for the secret |
+| `k8s.secret.name` | Yes | Name of the K8s Secret to create |
+
+### Retrieving Secrets for External Deployments
+
+The syncer always writes a **central copy** of every synced secret to the `secrets` namespace, in addition to the target namespace. This allows operators to retrieve client credentials for applications deployed outside this cluster:
+
+```bash
+# View the central copy
+kubectl get secret gitea-oidc-credentials -n secrets -o yaml
+
+# Extract the client secret for use elsewhere
+kubectl get secret myapp-oidc-credentials -n secrets \
+  -o jsonpath='{.data.client-secret}' | base64 -d
+```
+
+This is useful when an application runs on a separate cluster or external infrastructure and needs the Keycloak-generated OIDC credentials provisioned manually (e.g., via a SealedSecret on the remote side).
+
+### Syncer Behavior Notes
+
+- The syncer runs as an ArgoCD **PostSync hook** — it executes after all Keycloak resources are healthy
+- `BeforeHookCreation` delete policy ensures old Job is cleaned up before each run
+- If the target namespace doesn't exist, the target write is skipped with a warning (the central copy still happens)
+- A central copy is **always** written to the `secrets` namespace for every synced client
+- The syncer uses the `keycloak-credentials` secret for admin authentication
+- Created secrets have the label `app.kubernetes.io/managed-by: keycloak-secret-syncer`
+
+---
+
 ## Troubleshooting
 
 ### Application Not Deploying
@@ -1579,4 +1709,4 @@ Now that you understand the basics:
 - Docs: [Full documentation index](README.md)
 - Help: Contact platform team
 
-**Last Updated**: 2026-03-16
+**Last Updated**: 2026-04-16