bs cfg

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