feat(keycloak): property-manager login theme + how-to-apply guide

keycloak-theme/.gitignore

@@ -0,0 +1,60 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules
+jspm_packages
+
+# Optional npm cache directory
+.npm
+
+# yarn cache directory
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+
+# Optional REPL history
+.node_repl_history
+
+.vscode
+
+.DS_Store
+
+/dist
+
+/dist_keycloak
+/build
+/storybook-static
+
+# build output of `jsx-email`
+/.rendered

keycloak-theme/.prettierignore

@@ -0,0 +1,6 @@
+node_modules/
+/dist/
+/dist_keycloak/
+/public/keycloakify-dev-resources/
+/.vscode/
+/.yarn_home/

keycloak-theme/.prettierrc.json

@@ -0,0 +1,25 @@
+{
+    "printWidth": 90,
+    "tabWidth": 4,
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": false,
+    "trailingComma": "none",
+    "bracketSpacing": true,
+    "arrowParens": "avoid",
+    "overrides": [
+        {
+            "files": [
+                "**/login/pages/*.tsx",
+                "**/account/pages/*.tsx",
+                "**/login/Template.tsx",
+                "**/account/Template.tsx",
+                "**/login/UserProfileFormFields.tsx",
+                "KcApp.tsx"
+            ],
+            "options": {
+                "printWidth": 150
+            }
+        }
+    ]
+}

keycloak-theme/.storybook/main.ts

@@ -0,0 +1,12 @@
+import type { StorybookConfig } from "@storybook/react-vite";
+
+const config: StorybookConfig = {
+    stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+    addons: [],
+    framework: {
+        name: "@storybook/react-vite",
+        options: {}
+    },
+    staticDirs: ["../public"]
+};
+export default config;

keycloak-theme/.storybook/preview-head.html

@@ -0,0 +1,25 @@
+<style>
+    body.sb-show-main.sb-main-padded {
+        padding: 0;
+    }
+
+    /* Following styles are just meant to avoid white flash when switching from one story to another */
+    @keyframes fadeToTransparent {
+        from {
+            background-color: #393939;
+        }
+
+        to {
+            background-color: transparent;
+        }
+    }
+    html {
+        animation: fadeToTransparent 500ms forwards ease-in;
+    }
+    body > .sb-preparing-docs {
+        visibility: hidden;
+    }
+    body > .sb-preparing-story {
+        visibility: hidden;
+    }
+</style>

keycloak-theme/.storybook/preview.ts

@@ -0,0 +1,14 @@
+import type { Preview } from "@storybook/react";
+
+const preview: Preview = {
+    parameters: {
+        controls: {
+            matchers: {
+                color: /(background|color)$/i,
+                date: /Date$/i
+            }
+        }
+    }
+};
+
+export default preview;

keycloak-theme/APPLYING-THE-THEME.md

@@ -0,0 +1,115 @@
+# Applying the `property-manager` Keycloak login theme
+
+This is a **Keycloakify 11** project that produces the custom **`property-manager`** login theme
+used by the `prorentallb` realm (the "Property Manager" branded sign-in page). It is **already
+built and live on prod** (`fm-keycloak`, Keycloak 26); this guide is how to build it and apply it
+in any Keycloak from scratch.
+
+- **Theme name (what you select in Keycloak):** `property-manager` (set in `vite.config.ts`)
+- **Scope:** login theme only (`accountThemeImplementation: "none"`)
+- **Source:** `src/login/` (`KcPage.tsx`, `Template.tsx`, `theme.css`, `i18n.ts`)
+- Only the **source** is committed. The `node_modules/`, `dist/`, and `dist_keycloak/` (the built
+  jars) are gitignored build outputs — you produce them with the build step below.
+
+---
+
+## 1. Build the theme jar
+
+```bash
+cd keycloak-theme
+npm install                     # first time only (Node 18+ / 20+)
+npm run build-keycloak-theme
+```
+
+This emits two jars in `dist_keycloak/`:
+
+| Jar | Use for |
+|-----|---------|
+| `keycloak-theme-for-kc-all-other-versions.jar` | **Keycloak 26 (prod) and any modern KC** — use this one |
+| `keycloak-theme-for-kc-22-to-25.jar` | only Keycloak 22–25 |
+
+> ⚠️ Prod runs Keycloak 26.6.3 → always deploy the **`all-other-versions`** jar. Picking the
+> `22-to-25` jar on KC26 silently fails to load the theme.
+
+---
+
+## 2. Deploy the jar to Keycloak
+
+### Prod (Docker Compose — how it's actually wired today)
+`fm-keycloak` loads providers from a mounted `keycloak-providers/` dir via an **additive**
+`docker-compose.override.yml` (in `/opt/forward-mena/` on the VPS):
+
+```yaml
+# docker-compose.override.yml  (additive — touches nothing else in the stack)
+services:
+  keycloak:
+    volumes:
+      - ./keycloak-providers:/opt/keycloak/providers
+```
+
+Deploy / update the theme:
+```bash
+# from the compose dir (/opt/forward-mena on the VPS)
+mkdir -p keycloak-providers
+cp <path>/keycloak-theme/dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar keycloak-providers/
+docker compose up -d keycloak      # recreate so KC loads the provider on boot
+```
+Keycloak 26 (Quarkus) discovers provider jars in `/opt/keycloak/providers/` and runs its
+augmentation on startup — no separate `kc.sh build` step is needed for the `start` command used here.
+
+### Any other Keycloak (bare install / different container)
+Copy the jar into the server's providers dir and restart:
+```bash
+cp keycloak-theme-for-kc-all-other-versions.jar $KEYCLOAK_HOME/providers/
+# containerized: docker cp … <kc-container>:/opt/keycloak/providers/ && docker restart <kc-container>
+$KEYCLOAK_HOME/bin/kc.sh build       # only if your setup uses the explicit build step
+# then restart Keycloak
+```
+
+---
+
+## 3. Apply it in the Keycloak admin settings
+
+1. Open the **admin console** → top-left realm switcher → select realm **`prorentallb`**
+   (prod: `https://prorentallb.cloud/keycloack/admin`).
+2. Left nav → **Realm settings** → **Themes** tab.
+3. **Login theme** → choose **`property-manager`** from the dropdown.
+   *(If it's not in the list, the jar didn't load — re-check step 2 and that KC was restarted.)*
+4. Click **Save**.
+
+That's it — realm-wide. (You can also set it per-client under Clients → `prorentallb-web` → not
+needed here since it's the realm default.)
+
+Equivalent via the Admin REST API (if you script it):
+```
+PUT /admin/realms/prorentallb   { "loginTheme": "property-manager" }
+```
+
+---
+
+## 4. Verify
+
+Open the app's **Sign in** (it redirects to `…/keycloack/realms/prorentallb/protocol/openid-connect/auth…`)
+and confirm the Property Manager branding renders.
+
+> Testing the authorize URL **directly** in a browser needs a PKCE `code_challenge` (the
+> `prorentallb-web` client enforces PKCE) and `prompt=login`. Easiest is just to click "Sign in"
+> from the app.
+
+---
+
+## 5. Rollback
+
+Set **Login theme** back to `keycloak` (the default) in Realm settings → Themes → Save. To remove
+the provider entirely: delete the jar from `keycloak-providers/`, delete the override's volume line,
+and `docker compose up -d keycloak`.
+
+---
+
+## Gotchas (learned building this)
+
+- **KC26 = the `all-other-versions` jar**, not `22-to-25`.
+- The realm has **i18n OFF**, so the login page is **English-only** regardless of `kc_locale`.
+- PatternFly reskin traps handled in `src/login/theme.css`: the `.pf-c-input-group` white background
+  and the `#kc-info-wrapper` `#F0F0F0` band — if you restyle, watch those two.
+- After any provider-jar change, the **KC container must be recreated/restarted** to pick it up.

keycloak-theme/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 GitHub user u/garronej
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keycloak-theme/README.md

@@ -0,0 +1,58 @@
+<p align="center">
+    <i>🚀 <a href="https://keycloakify.dev">Keycloakify</a> v11 starter 🚀</i>
+    <br/>
+    <br/>
+</p>
+
+# Quick start
+
+```bash
+git clone https://github.com/keycloakify/keycloakify-starter
+cd keycloakify-starter
+yarn install # Or use an other package manager, just be sure to delete the yarn.lock if you use another package manager.
+```
+
+# Testing the theme locally
+
+[Documentation](https://docs.keycloakify.dev/testing-your-theme)
+
+# How to customize the theme
+
+[Documentation](https://docs.keycloakify.dev/css-customization)
+
+# Building the theme
+
+You need to have [Maven](https://maven.apache.org/) installed to build the theme (Maven >= 3.1.1, Java >= 7).  
+The `mvn` command must be in the $PATH.
+
+-   On macOS: `brew install maven`
+-   On Debian/Ubuntu: `sudo apt-get install maven`
+-   On Windows: `choco install openjdk` and `choco install maven` (Or download from [here](https://maven.apache.org/download.cgi))
+
+```bash
+npm run build-keycloak-theme
+```
+
+Note that by default Keycloakify generates multiple .jar files for different versions of Keycloak.  
+You can customize this behavior, see documentation [here](https://docs.keycloakify.dev/features/compiler-options/keycloakversiontargets).
+
+# Initializing the account theme
+
+```bash
+npx keycloakify initialize-account-theme
+```
+
+# Initializing the email theme
+
+```bash
+npx keycloakify initialize-email-theme
+```
+
+# GitHub Actions
+
+The starter comes with a generic GitHub Actions workflow that builds the theme and publishes
+the jars [as GitHub releases artifacts](https://github.com/keycloakify/keycloakify-starter/releases/tag/v10.0.0).  
+To release a new version **just update the `package.json` version and push**.
+
+To enable the workflow go to your fork of this repository on GitHub then navigate to:
+`Settings` > `Actions` > `Workflow permissions`, select `Read and write permissions`.

keycloak-theme/eslint.config.js

@@ -0,0 +1,48 @@
+import typescriptEslint from "typescript-eslint";
+import reactRefresh from "eslint-plugin-react-refresh";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import eslintConfigPrettier from "eslint-config-prettier";
+import globals from "globals";
+import js from "@eslint/js";
+import storybook from "eslint-plugin-storybook";
+
+export default typescriptEslint.config(
+  js.configs.recommended,
+  ...typescriptEslint.configs.recommended,
+  react.configs.flat.recommended,
+  react.configs.flat["jsx-runtime"],
+  eslintConfigPrettier,
+  ...storybook.configs["flat/recommended"],
+  {
+    ignores: ["dist/**", "public/**"],
+  },
+  {
+    plugins: {
+      "react-refresh": reactRefresh,
+      "react-hooks": reactHooks,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+    rules: {
+      "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
+      "react-hooks/exhaustive-deps": "off",
+      "@typescript-eslint/no-redeclare": "off",
+      "no-labels": "off",
+    },
+  },
+  {
+    files: ["**/*.stories.*"],
+    rules: {
+      "import/no-anonymous-default-export": "off",
+    },
+  },
+);