new

docs/REFERENCE.md

@@ -997,6 +997,7 @@ ignore:
 - **Important**: `dangerouslyAllowSignInWithoutUserInCatalog` must be nested inside the resolver object, not at the provider level
 
 **Keycloak User/Group Sync**:
+- The `backstage` Keycloak client has `serviceAccountsEnabled: true` with `realm-management` roles (`view-users`, `query-users`, `view-groups`, `query-groups`) — assigned automatically by the registrar
 - 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
@@ -1082,9 +1083,10 @@ upstream:
 2. For each config Secret, parses `client.json` and computes a config hash
 3. Skips if hash matches annotation and credential Secret already exists
 4. Creates or updates the Keycloak client via Admin API
-5. Fetches the generated client secret
-6. Upserts credential Secret in target namespace + central `secrets` namespace
-7. Annotates config Secret with sync status, config hash, and timestamp
+5. If `serviceAccountsEnabled: true` and `serviceAccountRoles` defined, assigns service account roles (e.g., `realm-management` → `view-users`)
+6. Fetches the generated client secret
+7. Upserts credential Secret in target namespace + central `secrets` namespace
+8. Annotates config Secret with sync status, config hash, and timestamp
 
 **Resources**:
 - `ServiceAccount`: `keycloak-client-registrar` (namespace: `keycloak`)