feat: add keycloak oidc support and docs verification

Author: thorsten

.github/workflows/build.yml

@@ -62,6 +62,14 @@ jobs:
           package-manager-cache: false
           node-version: 24
 
+      - name: Setup Python for docs build
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+
+      - name: Install MkDocs
+        run: python -m pip install --upgrade pip mkdocs
+
       - name: Setup pnpm
         uses: pnpm/action-setup@v6
         with:
@@ -90,3 +98,6 @@ jobs:
 
       - name: Run Vitest tests
         run: pnpm test
+
+      - name: Build documentation
+        run: mkdocs build --strict

composer.json

@@ -135,6 +135,7 @@
     "test:coverage": "./phpmyfaq/src/libs/bin/phpunit --coverage-text",
     "test:coverage-html": "./phpmyfaq/src/libs/bin/phpunit --coverage-html coverage",
     "bench": "./phpmyfaq/src/libs/bin/phpbench run tests/Benchmarks --report=aggregate",
+    "docs:build": "mkdocs build --strict",
     "version:get": "php scripts/get-version.php",
     "version:sync": "pnpm version $(php scripts/get-version.php) --no-git-tag-version --allow-same-version",
     "version:check": "php scripts/check-version.php"

docs/administration.md

@@ -499,7 +499,7 @@ Navigate to the **Configuration → Translation** tab to configure your translat
 - **Amazon**: AWS Access Key ID, Secret Access Key, and region
 - **LibreTranslate**: Server URL and optional API key
 
-For detailed setup instructions for each provider, see the [AI Translation Guide](9-ai-translation.md).
+For detailed setup instructions for each provider, see the [AI Translation Guide](ai-translation.md).
 
 #### 5.2.13.3 Translating Content
 
@@ -596,7 +596,7 @@ The AI will translate:
 - Re-translate if formatting is broken
 
 For comprehensive documentation, see:
-- [Complete AI Translation Guide](9-ai-translation.md) - Full documentation
+- [Complete AI Translation Guide](ai-translation.md) - Full documentation
 
 ## 5.3 Statistics
 
@@ -791,7 +791,7 @@ To back up the whole data located on your web server, you can run our simple bac
 Here you can edit the general, FAQ specific, search, spam protection, spam control center, SEO related, layout
 settings, Mail setup for SMTP, API settings, online update settings, and if enabled, LDAP configuration of phpMyFAQ.
 
-You can find a detailed description of all settings in the [Configuration key reference](8-configuration.md).
+You can find a detailed description of all settings in the [Configuration key reference](configuration.md).
 
 ### 5.6.2 FAQ Multi-sites
 
@@ -879,14 +879,19 @@ phpMyFAQ can integrate with external identity providers for administrator and fr
 
 Keycloak support uses OpenID Connect Authorization Code flow with PKCE.
 You can enable it in the administration under `Configuration` -> `Security` -> `Keycloak`.
+For a worked configuration example, see the dedicated [Keycloak Integration guide](keycloak.md).
 
 Recommended Keycloak client settings:
 
 - Client type: confidential
 - Standard flow enabled
 - Direct access grants disabled unless you need them for other tools
+- PKCE code challenge method: `S256`
+- Root URL: `https://faq.example.com/`
+- Home URL: `https://faq.example.com/`
 - Valid redirect URI: `https://faq.example.com/auth/keycloak/callback`
 - Valid post logout redirect URI: `https://faq.example.com/`
+- Web origin: `https://faq.example.com`
 
 Minimum phpMyFAQ configuration:
 
@@ -897,27 +902,47 @@ Minimum phpMyFAQ configuration:
 5. Set the `Client secret`
 6. Set the `Redirect URI` to your phpMyFAQ callback URL
 7. Keep `Scopes` at least on `openid profile email`
+8. Optionally set `Logout redirect URL` to the page users should see after provider logout
+
+Example phpMyFAQ values for a production setup:
+
+- `keycloak.baseUrl`: `https://sso.example.com`
+- `keycloak.realm`: `faq`
+- `keycloak.clientId`: `phpmyfaq`
+- `keycloak.redirectUri`: `https://faq.example.com/auth/keycloak/callback`
+- `keycloak.scopes`: `openid profile email`
+- `keycloak.logoutRedirectUrl`: `https://faq.example.com/`
 
 Optional settings:
 
 - Enable automatic provisioning if phpMyFAQ should create local users on first successful Keycloak login
 - Enable automatic group assignment if phpMyFAQ should assign local groups from Keycloak roles
+- Enable group synchronization on login if phpMyFAQ should remove stale memberships for mapped Keycloak groups
 - Add a JSON role-to-group mapping if Keycloak role names should map to different phpMyFAQ group names
 - Set a logout redirect URL if users should return to a specific page after provider logout
+- Use a JSON mapping such as `{"admin":"Administrators","faq-editors":"Editors"}` if Keycloak role names and phpMyFAQ group names differ
 
 phpMyFAQ resolves users in this order:
 
-1. preferred username from Keycloak
-2. existing user by email address
-3. automatic provisioning if enabled
+1. existing user linked by stored Keycloak subject (`sub`)
+2. preferred username from Keycloak
+3. existing user by email address
+4. automatic provisioning if enabled
 
 If automatic provisioning is disabled, users must already exist in phpMyFAQ before they can sign in with Keycloak.
 
-Group assignment is additive in the current implementation:
+Group assignment behavior:
 
-- mapped or unmapped Keycloak roles can create phpMyFAQ groups automatically
+- only roles listed in the JSON mapping are managed by phpMyFAQ
 - matched groups are added to the user on login
-- existing phpMyFAQ group memberships are not removed automatically
+- if group synchronization on login is enabled, stale memberships for mapped groups are removed during login
+- phpMyFAQ groups outside the configured Keycloak mapping are left untouched
+
+Troubleshooting:
+
+- If login works but logout does not return to phpMyFAQ, verify `Valid post logout redirect URI` in Keycloak and `keycloak.logoutRedirectUrl` in phpMyFAQ
+- If users are created but not added to groups, make sure permission level `medium` is enabled and the Keycloak roles actually match your JSON mapping keys
+- If an existing user cannot log in, check whether the stored Keycloak subject (`sub`) is already linked to a different account
 
 ### 5.7.2 Using Microsoft Entra ID
 

docs/configuration.md

@@ -133,8 +133,9 @@ each setting controls. These values are set during installation and can be chang
 | `keycloak.scopes`                           | Scopes | `openid profile email` | Space-separated scopes requested during login. |
 | `keycloak.autoProvision`                    | Automatically create phpMyFAQ users on first Keycloak login | `false` | When enabled, phpMyFAQ creates a local user automatically if no matching account exists yet. |
 | `keycloak.groupAutoAssign`                  | Automatically assign phpMyFAQ groups from Keycloak roles | `false` | When enabled and permission level `medium` is active, phpMyFAQ assigns users to groups derived from Keycloak roles on login. |
-| `keycloak.groupMapping`                     | Role to group mapping | *(empty)* | JSON object mapping Keycloak role names to phpMyFAQ group names, for example `{"admin":"Administrators"}`. Unmapped roles keep their original name. |
-| `keycloak.logoutRedirectUrl`                | Logout redirect URL | *(empty)* | URL users should be redirected to after logging out from Keycloak. |
+| `keycloak.groupSyncOnLogin`                 | Synchronize mapped phpMyFAQ groups on login | `false` | When enabled, phpMyFAQ also removes stale memberships for groups managed by the Keycloak role mapping during login. |
+| `keycloak.groupMapping`                     | Role to group mapping | *(empty)* | JSON object mapping Keycloak role names to phpMyFAQ group names, for example `{"admin":"Administrators","faq-editors":"Editors"}`. Only mapped roles are managed for assignment and synchronization. |
+| `keycloak.logoutRedirectUrl`                | Logout redirect URL | *(empty)* | URL users should be redirected to after logging out from Keycloak, for example `https://faq.example.com/`. |
 | `security.enableGoogleReCaptchaV2`          | Enable Invisible Google ReCAPTCHA v2 | `false` | Enables Google reCAPTCHA v2 to protect forms from spam and abuse. |
 | `security.googleReCaptchaV2SiteKey`         | Google ReCAPTCHA v2 site key | *(empty)* | The site key from your Google reCAPTCHA v2 registration. |
 | `security.googleReCaptchaV2SecretKey`       | Google ReCAPTCHA v2 secret key | *(empty)* | The secret key from your Google reCAPTCHA v2 registration. |

docs/keycloak.md

@@ -0,0 +1,127 @@
+# Keycloak Integration
+
+phpMyFAQ supports Keycloak as an OpenID Connect provider for frontend and administration logins.
+The integration uses Authorization Code flow with PKCE.
+
+## 1. Prerequisites
+
+Before you configure phpMyFAQ, make sure you have:
+
+- a reachable Keycloak server, for example `https://sso.example.com`
+- a realm for phpMyFAQ users, for example `faq`
+- a confidential client for phpMyFAQ
+- the public URL of your phpMyFAQ installation, for example `https://faq.example.com/`
+
+## 2. Recommended Keycloak client settings
+
+Recommended client settings for a phpMyFAQ installation at `https://faq.example.com/`:
+
+- Client type: confidential
+- Standard flow enabled
+- Direct access grants are disabled unless required for another integration
+- Service accounts disabled
+- PKCE code challenge method: `S256`
+- Root URL: `https://faq.example.com/`
+- Home URL: `https://faq.example.com/`
+- Valid redirect URIs:
+  - `https://faq.example.com/auth/keycloak/callback`
+- Valid post logout redirect URIs:
+  - `https://faq.example.com/`
+- Web origins:
+  - `https://faq.example.com`
+
+## 3. phpMyFAQ configuration
+
+In phpMyFAQ, open:
+
+- `Configuration`
+- `Security`
+- `Keycloak`
+
+Typical values:
+
+- `keycloak.enable`: `true`
+- `keycloak.baseUrl`: `https://sso.example.com`
+- `keycloak.realm`: `faq`
+- `keycloak.clientId`: `phpmyfaq`
+- `keycloak.clientSecret`: `<client secret from Keycloak>`
+- `keycloak.redirectUri`: `https://faq.example.com/auth/keycloak/callback`
+- `keycloak.scopes`: `openid profile email`
+- `keycloak.logoutRedirectUrl`: `https://faq.example.com/`
+
+Optional user and group settings:
+
+- `keycloak.autoProvision`: `true`
+- `keycloak.groupAutoAssign`: `true`
+- `keycloak.groupSyncOnLogin`: `true`
+- `keycloak.groupMapping`: `{"admin":"Administrators","faq-editors":"Editors"}`
+
+## 4. User resolution and account linking
+
+phpMyFAQ resolves Keycloak users in this order:
+
+1. existing user linked by stored Keycloak subject (`sub`)
+2. preferred username from Keycloak
+3. existing user by email address
+4. automatic provisioning, if enabled
+
+The stored Keycloak subject is the durable link between a local phpMyFAQ account and the external identity.
+
+If automatic provisioning is disabled, users must already exist in phpMyFAQ before they can sign in.
+
+## 5. Group mapping behavior
+
+Group handling is intentionally conservative:
+
+- only roles listed in `keycloak.groupMapping` are managed by phpMyFAQ
+- mapped groups are added on login when `keycloak.groupAutoAssign` is enabled
+- stale memberships are removed only for mapped groups when `keycloak.groupSyncOnLogin` is enabled
+- phpMyFAQ groups outside the configured mapping are left untouched
+
+Example mapping:
+
+```json
+{
+  "admin": "Administrators",
+  "faq-editors": "Editors"
+}
+```
+
+This means:
+
+- Keycloak role `admin` maps to phpMyFAQ group `Administrators`
+- Keycloak role `faq-editors` maps to phpMyFAQ group `Editors`
+
+## 6. Logout behavior
+
+phpMyFAQ logs the user out locally and then redirects to Keycloak logout when:
+
+- Keycloak sign-in is enabled
+- the current user is authenticated through Keycloak
+
+For a reliable provider logout:
+
+- set `keycloak.logoutRedirectUrl` in phpMyFAQ
+- make sure the same URL is listed as a valid post-logout redirect URI in Keycloak
+
+## 7. Troubleshooting
+
+If login works but logout does not return to phpMyFAQ:
+
+- verify `keycloak.logoutRedirectUrl`
+- verify the matching valid post-logout redirect URI in Keycloak
+
+If users are created but not assigned to groups:
+
+- verify permission level `medium`
+- verify `keycloak.groupAutoAssign` is enabled
+- verify the Keycloak role names exactly match the JSON mapping keys
+
+If group synchronization removes the wrong memberships:
+
+- check `keycloak.groupMapping`
+- remember that only mapped groups are managed
+
+If an existing user cannot log in:
+
+- check whether the stored Keycloak subject (`sub`) is already linked to another local account

mkdocs.yml

@@ -2,6 +2,9 @@ site_name: phpMyFAQ v4.2
 theme:
   name: readthedocs
   highlightjs: true
+not_in_nav: |
+  /s3-storage-checklist.md
+  /keys/**
 extra_css:
   - css/custom.css
 plugins:
@@ -15,9 +18,10 @@ nav:
   - 6. Use phpMyFAQ: 'usage.md'
   - 7. Manage phpMyFAQ: 'administration.md'
   - 8. Configuration reference: 'configuration.md'
-  - 9. AI-Assisted Translation feature: 'ai-translation.md'
-  - 10. Developer documentation: 'development.md'
-  - 11. Plugins: 'plugins.md'
-  - 12. MCP Server: 'mcp-server.md'
-  - 13. Release: 'release.md'
-  - 14. Thank you!: 'thank-you.md'
+  - 9. Keycloak Integration: 'keycloak.md'
+  - 10. AI-Assisted Translation feature: 'ai-translation.md'
+  - 11. Developer documentation: 'development.md'
+  - 12. Plugins: 'plugins.md'
+  - 13. MCP Server: 'mcp-server.md'
+  - 14. Release: 'release.md'
+  - 15. Thank you!: 'thank-you.md'

package.json

@@ -38,6 +38,7 @@
     "release:artifacts": "./scripts/prepare-release-artifacts.sh",
     "release:sign": "./scripts/sign-release-artifacts.sh",
     "sbom": "./scripts/generate-sbom.sh",
+    "docs:build": "mkdocs build --strict",
     "eslint": "eslint .",
     "lint": "prettier --check .",
     "lint:fix": "prettier --write .",

phpmyfaq/admin/assets/src/configuration/configuration.test.ts

@@ -361,6 +361,7 @@ describe('Configuration Functions', () => {
         <div id="keycloak">
           <div class="pmf-config-item" data-config-key="keycloak.enable">Enable Keycloak sign-in</div>
           <div class="pmf-config-item" data-config-key="keycloak.clientId">Client ID</div>
+          <div class="pmf-config-item" data-config-key="keycloak.groupSyncOnLogin">Synchronize groups on login</div>
           <div class="pmf-config-item" data-config-key="keycloak.groupMapping">Role to group mapping</div>
         </div>
         <div id="upgrade">

phpmyfaq/src/phpMyFAQ/Auth/AuthKeycloak.php

@@ -160,31 +160,56 @@ private function assignUserToGroups(int $userId): void
             return;
         }
 
-        $roleNames = $this->extractRoleNames();
-        if ($roleNames === []) {
+        $mediumPermission = $this->createMediumPermission();
+        $groupMapping = $this->getGroupMapping();
+        if ($groupMapping === []) {
             return;
         }
 
-        $mediumPermission = $this->createMediumPermission();
-        $groupMapping = $this->getGroupMapping();
+        $currentGroupIds = $mediumPermission->getUserGroups($userId);
+        $desiredGroupIds = [];
+        $roleNames = $this->extractRoleNames();
 
         foreach ($roleNames as $roleName) {
-            if (!isset($groupMapping[$roleName])) {
+            if (!array_key_exists($roleName, $groupMapping)) {
                 continue;
             }
-
             $faqGroupName = $groupMapping[$roleName];
             $groupId = $mediumPermission->findOrCreateGroupByName($faqGroupName);
-
             if ($groupId <= 0) {
                 continue;
             }
 
+            $desiredGroupIds[] = $groupId;
+            if (in_array($groupId, $currentGroupIds, true)) {
+                continue;
+            }
+
             $mediumPermission->addToGroup($userId, $groupId);
             $this->configuration
                 ->getLogger()
                 ->info(sprintf('Added Keycloak user #%d to group %s', $userId, $faqGroupName));
         }
+
+        if (!$this->shouldSynchronizeGroupsOnLogin()) {
+            return;
+        }
+
+        foreach (array_values(array_unique($groupMapping)) as $groupName) {
+            $groupId = $mediumPermission->getGroupId($groupName);
+            if ($groupId <= 0) {
+                continue;
+            }
+
+            if (!in_array($groupId, $currentGroupIds, true) || in_array($groupId, $desiredGroupIds, true)) {
+                continue;
+            }
+
+            $mediumPermission->removeFromGroup($userId, $groupId);
+            $this->configuration
+                ->getLogger()
+                ->info(sprintf('Removed Keycloak user #%d from group %s', $userId, $groupName));
+        }
     }
 
     /**
@@ -242,6 +267,11 @@ private function toBool(mixed $value): bool
         return filter_var($value, FILTER_VALIDATE_BOOLEAN);
     }
 
+    private function shouldSynchronizeGroupsOnLogin(): bool
+    {
+        return $this->toBool($this->configuration->get(item: 'keycloak.groupSyncOnLogin'));
+    }
+
     private function createUser(): User
     {
         if ($this->userFactory instanceof Closure) {

phpmyfaq/src/phpMyFAQ/Controller/Administration/Api/ConfigurationTabController.php

@@ -331,6 +331,7 @@ private function logSecurityConfigChanges(array $changedKeys, array $oldConfig,
             'keycloak.scopes',
             'keycloak.autoProvision',
             'keycloak.groupAutoAssign',
+            'keycloak.groupSyncOnLogin',
             'keycloak.groupMapping',
             'keycloak.logoutRedirectUrl',
         ];