From 1a4d8092a77bd07d4b9da7c790c8cfbe66982fe9 Mon Sep 17 00:00:00 2001
From: Danijel Simeunovic <danijel.simeunovic@fortedigital.com>
Date: Thu, 23 Apr 2026 23:26:12 +0200
Subject: [PATCH] bs cfg

---
 docs/REFERENCE.md                       | 21 ++++++++++++++++++---
 infra/values/base/backstage-values.yaml | 13 ++++++++-----
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md
index 05e4c89..4cfca12 100644
--- a/docs/REFERENCE.md
+++ b/docs/REFERENCE.md
@@ -983,7 +983,7 @@ ignore:
 - SecurityContext configured for vanilla Kubernetes (non-OpenShift)
 - Traefik ingress with `websecure` entrypoint
 - App title: "Forte Developer Portal"
-- Dynamic plugins: loads `dynamic-plugins.default.yaml` (all 27+ bundled plugins)
+- Dynamic plugins: loads `dynamic-plugins.default.yaml` (all 27+ bundled plugins), plus Keycloak catalog backend module enabled explicitly
 - Catalog rules: Component, System, API, Resource, Location, Template, Group, User, Domain
 
 **Authentication** (Keycloak OIDC):
@@ -991,8 +991,16 @@ ignore:
 - Config Secret: `cluster-resources/backstage-keycloak-client-config.yaml`
 - Kyverno clones it → registrar creates `backstage-oidc-credentials` Secret in `backstage` namespace
 - Credential keys: `AUTH_OIDC_CLIENT_ID`, `AUTH_OIDC_CLIENT_SECRET` (loaded via `extraEnvVarsSecrets`)
+- Session secret: `backstage-session-secret` with `AUTH_SESSION_SECRET` (required for OIDC popup flow)
 - Redirect URI: `https://backstage.forteapps.net/api/auth/oidc/handler/frame`
-- Sign-in resolver: `emailMatchingUserEntityProfileEmail`
+- Sign-in resolver: `emailMatchingUserEntityProfileEmail` with `dangerouslyAllowSignInWithoutUserInCatalog: true`
+- **Important**: `dangerouslyAllowSignInWithoutUserInCatalog` must be nested inside the resolver object, not at the provider level
+
+**Keycloak User/Group Sync**:
+- The `keycloakOrg` catalog provider auto-imports users and groups from the `forte` realm
+- Requires the Keycloak dynamic plugin to be enabled (pre-installed but disabled by default in RHDH)
+- Syncs every 30 minutes with 15-second initial delay
+- Once users are synced, the `emailMatchingUserEntityProfileEmail` resolver matches them by email
 
 **Catalog Discovery** (Gitea):
 - Auto-discovers `catalog-info.yaml` from all repos in the `Forte` organization
@@ -1018,14 +1026,21 @@ spec:
 Repos with this file are auto-discovered — no manual registration needed.
 
 **Dynamic Plugins**:
-Add plugins at runtime via `global.dynamic.plugins` in values — no image rebuild:
+RHDH ships bundled plugins that are pre-installed but may be disabled by default. Enable them by setting `disabled: false`:
 ```yaml
 global:
   dynamic:
+    includes:
+    - dynamic-plugins.default.yaml
     plugins:
+    # Enable a pre-installed plugin (use local path from /opt/app-root/src/dynamic-plugins-root/)
+    - package: ./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic
+      disabled: false
+    # Or install an external plugin by npm package name
     - package: "@scope/my-plugin@1.0.0"
       integrity: "sha512-..."
 ```
+Currently enabled: `backstage-community-plugin-catalog-backend-module-keycloak-dynamic` (syncs Keycloak users/groups into catalog).
 
 **Per-cluster Configuration** (`infra/values/upc-dev/backstage-values.yaml`):
 ```yaml
diff --git a/infra/values/base/backstage-values.yaml b/infra/values/base/backstage-values.yaml
index 5b303d6..3474277 100644
--- a/infra/values/base/backstage-values.yaml
+++ b/infra/values/base/backstage-values.yaml
@@ -10,7 +10,10 @@ global:
   dynamic:
     includes:
     - dynamic-plugins.default.yaml
-    plugins: []
+    plugins:
+    # Keycloak backend catalog module — syncs users & groups into the catalog
+    - package: ./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic
+      disabled: false
 
 # Disable OpenShift Route (not on OpenShift)
 route:
@@ -61,12 +64,12 @@ upstream:
               clientId: ${AUTH_OIDC_CLIENT_ID}
               clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
               prompt: auto
-              # Allow login before User entities exist in the catalog.
-              # Remove once org data is populated.
-              dangerouslyAllowSignInWithoutUserInCatalog: true
               signIn:
                 resolvers:
-                - resolver: preferredUsernameMatchingUserEntityName
+                - resolver: emailMatchingUserEntityProfileEmail
+                  # Allow login before User entities exist in the catalog.
+                  # Remove once Keycloak org sync populates User entities.
+                  dangerouslyAllowSignInWithoutUserInCatalog: true
 
       # -- Gitea SCM integration (for catalog URL resolution)
       integrations: