docs

devbox.json

@@ -17,7 +17,9 @@
     "claude-code@latest",
     "go@latest",
     "dotnet-sdk@latest",
-    "opentofu@1.11.6"
+    "opentofu@1.11.6",
+    "_1password@latest",
+    "github-cli@latest"
   ],
   "shell": {
     "init_hook": [

docs/DEVELOPER-GUIDE.md

@@ -1336,16 +1336,34 @@ stringData:
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `clientId` | Yes | Keycloak client ID |
+| `clientId` | Yes | Keycloak client ID (must be unique in realm) |
-| `name` | Yes | Display name in Keycloak |
+| `name` | Yes | Display name in Keycloak UI |
-| `redirectUris` | Yes | Allowed redirect URIs |
+| `redirectUris` | Yes | Allowed OAuth redirect URLs (supports wildcards like `/*`) |
-| `webOrigins` | Yes | Allowed web origins (CORS) |
+| `webOrigins` | Yes | Allowed CORS origins |
-| `defaultClientScopes` | No | Scopes (default: `["openid", "email", "profile"]`) |
+| `defaultClientScopes` | No | OIDC scopes (default: `["openid", "email", "profile"]`) |
-| `protocolMappers` | No | Custom claim mappers (default: `[]`) |
+| `protocolMappers` | No | Custom claim mappers for tokens (see examples below) |
-| `secret.namespace` | No | Namespace for the credential Secret (default: source namespace) |
+| `secret.namespace` | No | Target namespace for credentials (default: `source-namespace` annotation value) |
-| `secret.name` | No | Name of the credential Secret (default: `<clientId>-oidc-credentials`) |
+| `secret.name` | No | Credential Secret name (default: `<clientId>-oidc-credentials`) |
-| `secret.keys.clientId` | No | Key name for client ID in credential Secret (default: `client-id`) |
+| `secret.keys.clientId` | No | Key name for client ID (default: `client-id`) |
-| `secret.keys.clientSecret` | No | Key name for client secret in credential Secret (default: `client-secret`) |
+| `secret.keys.clientSecret` | No | Key name for client secret (default: `client-secret`) |
+
+**Protocol Mappers Example**:
+```json
+"protocolMappers": [
+  {
+    "name": "groups",
+    "protocol": "openid-connect",
+    "protocolMapper": "oidc-group-membership-mapper",
+    "config": {
+      "claim.name": "groups",
+      "full.path": "false",
+      "id.token.claim": "true",
+      "access.token.claim": "true",
+      "userinfo.token.claim": "true"
+    }
+  }
+]
+```
 
 #### Step 2: Reference the Credential Secret
 

docs/REFERENCE.md

@@ -1242,9 +1242,18 @@ The realm uses a custom browser authentication flow (`browser-auto-idp`) that sk
 
 **Resources**:
 - `ServiceAccount`: `keycloak-client-registrar` (namespace: `keycloak`)
-- `ClusterRole`: `keycloak-client-registrar` (secrets: get/list/create/update/patch; namespaces: get/list)
+- `ClusterRole`: `keycloak-client-registrar` 
+  - Secrets: `get`, `list`, `create`, `update`, `patch`
+  - Namespaces: `get`, `list`
 - `ClusterRoleBinding`: `keycloak-client-registrar`
 - `CronJob`: `keycloak-client-registrar`
+  - **Schedule**: `*/2 * * * *` (every 2 minutes)
+  - **Concurrency Policy**: `Forbid` (prevents concurrent runs)
+  - **Backoff Limit**: 3 retries per job
+  - **History**: 1 successful job, 3 failed jobs retained
+  - **Resources**: 50m CPU / 64Mi memory (requests), 200m CPU / 128Mi memory (limits)
+
+**Container**: Alpine 3.20 with `curl` and `jq` installed
 
 **Kyverno Policy**: `keycloak-client-config-cloner` — clones labeled Secrets from app namespaces to `keycloak` namespace (see [Kyverno Policies](#kyverno-policies))