client cloner (#3)

Reviewed-on: #3
Reviewed-by: gitea_admin <admin@forteapps.net>
Co-authored-by: Danijel Simeunovic <danijel.simeunovic@fortedigital.com>
Co-committed-by: Danijel Simeunovic <danijel.simeunovic@fortedigital.com>

docs/DEVELOPER-GUIDE.md

@@ -1250,20 +1250,119 @@ 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.
+There are two ways to add an OIDC client, depending on your use case:
 
-### How It Works
+| Method | Best for | Who edits the infra repo? |
+|--------|----------|--------------------------|
+| **Self-service** (recommended) | New apps that deploy their own resources | App developer — no infra changes needed |
+| **Legacy (realm JSON)** | Existing clients already defined in forte-realm.json (e.g., Gitea) | Platform engineer |
 
-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
+Both methods are served by the **Keycloak Client Registrar** CronJob, which runs every 2 minutes.
 
-### Step 1: Add Client to Realm Config
+### Self-Service OIDC Client Registration
+
+This is the recommended flow for new applications. Your app deploys a labeled config Secret in its own namespace; the platform handles everything else.
+
+#### How It Works
+
+1. You deploy a Secret with label `keycloak.forteapps.net/client-config: "true"` containing a `client.json` definition
+2. A **Kyverno ClusterPolicy** (`keycloak-client-config-cloner`) clones it to the `keycloak` namespace
+3. The **Client Registrar CronJob** picks it up within 2 minutes:
+   - Registers (or updates) the client in Keycloak
+   - Fetches the auto-generated client secret
+   - Creates a credential Secret in your app's namespace
+   - Annotates the config Secret with sync status
+
+#### Step 1: Create the Config Secret
+
+Deploy this Secret in your application's namespace (e.g., as part of your Helm chart or Kustomize overlay):
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: keycloak-client-myapp
+  namespace: myapp
+  labels:
+    keycloak.forteapps.net/client-config: "true"
+stringData:
+  client.json: |
+    {
+      "clientId": "myapp",
+      "name": "My Application",
+      "redirectUris": ["https://myapp.forteapps.net/*"],
+      "webOrigins": ["https://myapp.forteapps.net"],
+      "defaultClientScopes": ["openid", "email", "profile"],
+      "protocolMappers": [],
+      "secret": {
+        "namespace": "myapp",
+        "name": "myapp-oidc-credentials",
+        "keys": { "clientId": "client-id", "clientSecret": "client-secret" }
+      }
+    }
+```
+
+**`client.json` fields**:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `clientId` | Yes | Keycloak client ID |
+| `name` | Yes | Display name in Keycloak |
+| `redirectUris` | Yes | Allowed redirect URIs |
+| `webOrigins` | Yes | Allowed web origins (CORS) |
+| `defaultClientScopes` | No | Scopes (default: `["openid", "email", "profile"]`) |
+| `protocolMappers` | No | Custom claim mappers (default: `[]`) |
+| `secret.namespace` | No | Namespace for the credential Secret (default: source namespace) |
+| `secret.name` | No | Name of the credential Secret (default: `<clientId>-oidc-credentials`) |
+| `secret.keys.clientId` | No | Key name for client ID in credential Secret (default: `client-id`) |
+| `secret.keys.clientSecret` | No | Key name for client secret in credential Secret (default: `client-secret`) |
+
+#### Step 2: Reference the Credential Secret
+
+In your application's deployment config, reference the credential Secret that the registrar creates:
+
+```yaml
+env:
+- name: OIDC_CLIENT_ID
+  valueFrom:
+    secretKeyRef:
+      name: myapp-oidc-credentials
+      key: client-id
+- name: OIDC_CLIENT_SECRET
+  valueFrom:
+    secretKeyRef:
+      name: myapp-oidc-credentials
+      key: client-secret
+```
+
+#### Step 3: Deploy and Wait
+
+Commit and push your changes. The credential Secret will appear within 2 minutes:
+
+```bash
+# Watch for the credential Secret to be created
+kubectl get secret myapp-oidc-credentials -n myapp -w
+
+# Check registrar logs
+kubectl logs -n keycloak job/$(kubectl get jobs -n keycloak --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}')
+
+# Check sync status on the config Secret
+kubectl get secret keycloak-client-myapp -n keycloak -o jsonpath='{.metadata.annotations}'
+```
+
+#### Change Detection
+
+The registrar computes a SHA-256 hash of `client.json` and stores it as an annotation. On subsequent runs, it skips processing if:
+- The hash hasn't changed, AND
+- The credential Secret already exists in the target namespace
+
+To force a re-sync, update any field in `client.json` (e.g., add a trailing space to `name`).
+
+### Legacy Method: Realm JSON
+
+Existing clients (like Gitea) are defined directly in `forte-realm.json` inside `keycloak-values.yaml`. The registrar syncs their secrets via client attributes.
+
+#### 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`:
 
@@ -1292,30 +1391,16 @@ In `infra/values/keycloak-values.yaml`, add a new entry to the `clients` array i
 
 **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`)
+- The `attributes` block tells the registrar where to create the K8s Secret
 - Set `client-id-key` / `client-secret-key` to match what the consuming app expects (defaults: `client-id` / `client-secret`)
 
-### Step 2: Reference the Secret in Your Application
-
-In your application's Helm values, reference the syncer-created secret:
+#### Step 2: Reference the Secret in Your Application
 
 ```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
 ```
 
-For Gitea-style oauth config:
-```yaml
-oauth:
-- name: "Forte"
-  provider: "openidConnect"
-  existingSecret: myapp-oidc-credentials # Gitea expects "key" and "secret" as fields
-  autoDiscoverUrl: "https://id.forteapps.net/realms/forte/.well-known/openid-configuration"
-```
-
-### Step 3: Commit and Push
+#### Step 3: Commit and Push
 
 ```bash
 cd ~/dev/k8s/launchpad
@@ -1324,27 +1409,9 @@ 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
+ArgoCD will sync the Keycloak config, and the registrar CronJob will pick up the new client within 2 minutes.
 
-### 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
+#### Legacy Sync Attribute Reference
 
 | Attribute | Required | Default | Description |
 |-----------|----------|---------|-------------|
@@ -1354,11 +1421,9 @@ kubectl get secret myapp-oidc-credentials -n myapp -o jsonpath='{.data.client-se
 | `k8s.secret.client-id-key` | No | `client-id` | Field name for the client ID in the K8s Secret |
 | `k8s.secret.client-secret-key` | No | `client-secret` | Field name for the client secret in the K8s Secret |
 
-**Note on key names:** Different applications expect different field names. For example, the Gitea Helm chart expects `key` and `secret`, while a generic OIDC consumer might expect `client-id` and `client-secret`. Use the optional key attributes to match what the consuming application expects.
-
 ### 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:
+The registrar 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
@@ -1369,16 +1434,13 @@ 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).
+### Registrar Behavior Notes
 
-### 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
+- The registrar runs as a CronJob every 2 minutes (`concurrencyPolicy: Forbid`)
 - 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`
+- The registrar uses the `keycloak-credentials` secret for admin authentication
+- Created secrets have the label `app.kubernetes.io/managed-by: keycloak-client-registrar`
 
 ---