feat(keycloak): extended the Keycloak support with role-to-group assignment

Author: thorsten

docs/administration.md

@@ -871,7 +871,55 @@ On this page, phpMyFAQ displays some relevant system information like PHP versio
 Please use this information when reporting bugs. Additionally, you can check the status of all translation files and see 
 if there are any missing translations.
 
-## 5.7 Using Microsoft Entra ID
+## 5.7 Using external identity providers
+
+phpMyFAQ can integrate with external identity providers for administrator and frontend logins.
+
+### 5.7.1 Using Keycloak
+
+Keycloak support uses OpenID Connect Authorization Code flow with PKCE.
+You can enable it in the administration under `Configuration` -> `Security` -> `Keycloak`.
+
+Recommended Keycloak client settings:
+
+- Client type: confidential
+- Standard flow enabled
+- Direct access grants disabled unless you need them for other tools
+- Valid redirect URI: `https://faq.example.com/auth/keycloak/callback`
+- Valid post logout redirect URI: `https://faq.example.com/`
+
+Minimum phpMyFAQ configuration:
+
+1. Enable `Keycloak sign-in`
+2. Set the `Keycloak base URL`, for example `https://sso.example.com`
+3. Set the `Realm`
+4. Set the `Client ID`
+5. Set the `Client secret`
+6. Set the `Redirect URI` to your phpMyFAQ callback URL
+7. Keep `Scopes` at least on `openid profile email`
+
+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
+- 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
+
+phpMyFAQ resolves users in this order:
+
+1. preferred username from Keycloak
+2. existing user by email address
+3. 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:
+
+- mapped or unmapped Keycloak roles can create phpMyFAQ groups automatically
+- matched groups are added to the user on login
+- existing phpMyFAQ group memberships are not removed automatically
+
+### 5.7.2 Using Microsoft Entra ID
 
 You can use our experimental Microsoft Entra ID support for user authentication as well.
 App Registrations in Azure are used to integrate applications with Microsoft Azure services,

docs/configuration.md

@@ -124,6 +124,17 @@ each setting controls. These values are set during installation and can be chang
 | `security.enableRegistration`               | Enable registration for visitors | `true` | Allows new users to register an account on the FAQ. |
 | `security.domainWhiteListForRegistrations`  | Allowed hosts for registrations | *(empty)* | A list of allowed email domains for new registrations. Leave empty to allow all domains. |
 | `security.enableSignInWithMicrosoft`        | Enable Sign in with Microsoft Entra ID | `false` | Enables authentication via Microsoft Entra ID (formerly Azure AD). |
+| `keycloak.enable`                           | Enable Keycloak sign-in | `false` | Enables OpenID Connect authentication via Keycloak for the frontend and admin login forms. |
+| `keycloak.baseUrl`                          | Keycloak base URL | *(empty)* | Base URL of the Keycloak server, for example `https://sso.example.com`. |
+| `keycloak.realm`                            | Realm | *(empty)* | Keycloak realm used for phpMyFAQ authentication. |
+| `keycloak.clientId`                         | Client ID | *(empty)* | OIDC client identifier configured in Keycloak. |
+| `keycloak.clientSecret`                     | Client secret | *(empty)* | Client secret configured for the Keycloak OIDC client. |
+| `keycloak.redirectUri`                      | Redirect URI | *(empty)* | Callback URL registered in the Keycloak client, usually `https://faq.example.com/auth/keycloak/callback`. |
+| `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. |
 | `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/index.md

@@ -20,7 +20,7 @@ phpMyFAQ also supports two-factor authentication (2FA) for enhanced security.
 An AI-assisted translation feature helps translate content into multiple languages using Google Cloud Translation, DeepL,
 Azure Translator, Amazon Translate, or LibreTranslate.
 A REST API is available for integration with other systems.
-It also supports OpenLDAP, Microsoft Active Directory, Microsoft Entra ID, and an MCP Server for AI agents.
+It also supports OpenLDAP, Microsoft Active Directory, Microsoft Entra ID, Keycloak, and an MCP Server for AI agents.
 The system is easy to install, thanks to its user-friendly installation script.
 
 phpMyFAQ is versatile

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

@@ -354,6 +354,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.groupMapping">Role to group mapping</div>
         </div>
         <div id="upgrade">
           <div class="pmf-config-item" data-config-key="upgrade.releaseEnvironment">Release environment</div>

phpmyfaq/src/phpMyFAQ/Auth/AuthKeycloak.php

@@ -25,6 +25,7 @@
 use phpMyFAQ\Configuration;
 use phpMyFAQ\Core\Exception;
 use phpMyFAQ\Enums\AuthenticationSourceType;
+use phpMyFAQ\Permission\MediumPermission;
 use phpMyFAQ\User;
 use SensitiveParameter;
 
@@ -37,6 +38,7 @@ public function __construct(
         private readonly array $claims,
         private readonly string $resolvedLogin,
         private readonly ?Closure $userFactory = null,
+        private readonly ?Closure $mediumPermissionFactory = null,
     ) {
         parent::__construct($configuration);
     }
@@ -62,6 +64,10 @@ public function create(string $login, #[SensitiveParameter] string $password, st
             'email' => $this->getEmail(),
         ]);
 
+        if ($this->shouldAssignGroups()) {
+            $this->assignUserToGroups($user->getUserId());
+        }
+
         return $result;
     }
 
@@ -127,6 +133,102 @@ private function userExists(string $login): bool
         return $user->getUserByLogin($login, false);
     }
 
+    private function shouldAssignGroups(): bool
+    {
+        return (
+            $this->toBool($this->configuration->get(item: 'keycloak.groupAutoAssign'))
+            && $this->configuration->get(item: 'security.permLevel') === 'medium'
+        );
+    }
+
+    private function assignUserToGroups(int $userId): void
+    {
+        if ($userId <= 0) {
+            return;
+        }
+
+        $roleNames = $this->extractRoleNames();
+        if ($roleNames === []) {
+            return;
+        }
+
+        $mediumPermission = $this->createMediumPermission();
+        $groupMapping = $this->getGroupMapping();
+
+        foreach ($roleNames as $roleName) {
+            $faqGroupName = $groupMapping[$roleName] ?? $roleName;
+            $groupId = $mediumPermission->findOrCreateGroupByName($faqGroupName);
+
+            if ($groupId <= 0) {
+                continue;
+            }
+
+            $mediumPermission->addToGroup($userId, $groupId);
+            $this->configuration
+                ->getLogger()
+                ->info(sprintf('Added Keycloak user %s to group %s', $this->resolvedLogin, $faqGroupName));
+        }
+    }
+
+    /**
+     * @return array<string>
+     */
+    private function extractRoleNames(): array
+    {
+        $roleNames = [];
+
+        $realmRoles = $this->claims['realm_access']['roles'] ?? [];
+        if (is_array($realmRoles)) {
+            foreach ($realmRoles as $realmRole) {
+                if (!is_string($realmRole) || $realmRole === '') {
+                    continue;
+                }
+
+                $roleNames[] = $realmRole;
+            }
+        }
+
+        $resourceAccess = $this->claims['resource_access'] ?? [];
+        if (is_array($resourceAccess)) {
+            foreach ($resourceAccess as $resource) {
+                $resourceRoles = is_array($resource) ? $resource['roles'] ?? null : null;
+                if (!is_array($resourceRoles)) {
+                    continue;
+                }
+
+                foreach ($resourceRoles as $resourceRole) {
+                    if (!is_string($resourceRole) || $resourceRole === '') {
+                        continue;
+                    }
+
+                    $roleNames[] = $resourceRole;
+                }
+            }
+        }
+
+        return array_values(array_unique($roleNames));
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    private function getGroupMapping(): array
+    {
+        $groupMapping = $this->configuration->get(item: 'keycloak.groupMapping');
+        if (!is_string($groupMapping) || trim($groupMapping) === '') {
+            return [];
+        }
+
+        $decoded = json_decode($groupMapping, associative: true);
+
+        return is_array($decoded) ? array_filter($decoded, is_string(...)) : [];
+    }
+
+    private function toBool(mixed $value): bool
+    {
+        return filter_var($value, FILTER_VALIDATE_BOOLEAN);
+    }
+
     private function createUser(): User
     {
         if ($this->userFactory instanceof Closure) {
@@ -135,4 +237,13 @@ private function createUser(): User
 
         return new User($this->configuration);
     }
+
+    private function createMediumPermission(): MediumPermission
+    {
+        if ($this->mediumPermissionFactory instanceof Closure) {
+            return ($this->mediumPermissionFactory)();
+        }
+
+        return new MediumPermission($this->configuration);
+    }
 }

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

@@ -330,6 +330,8 @@ private function logSecurityConfigChanges(array $changedKeys, array $oldConfig,
             'keycloak.redirectUri',
             'keycloak.scopes',
             'keycloak.autoProvision',
+            'keycloak.groupAutoAssign',
+            'keycloak.groupMapping',
             'keycloak.logoutRedirectUrl',
         ];
 

phpmyfaq/src/phpMyFAQ/Setup/Installation/DefaultDataSeeder.php

@@ -214,6 +214,8 @@ private static function buildDefaultConfig(): array
             'keycloak.redirectUri' => '',
             'keycloak.scopes' => 'openid profile email',
             'keycloak.autoProvision' => 'false',
+            'keycloak.groupAutoAssign' => 'false',
+            'keycloak.groupMapping' => '',
             'keycloak.logoutRedirectUrl' => '',
             'spam.checkBannedWords' => 'true',
             'spam.enableCaptchaCode' => null,

phpmyfaq/src/phpMyFAQ/Setup/Migration/Versions/Migration420Alpha.php

@@ -810,6 +810,8 @@ public function up(OperationRecorder $recorder): void
         $recorder->addConfig('keycloak.redirectUri', '');
         $recorder->addConfig('keycloak.scopes', 'openid profile email');
         $recorder->addConfig('keycloak.autoProvision', 'false');
+        $recorder->addConfig('keycloak.groupAutoAssign', 'false');
+        $recorder->addConfig('keycloak.groupMapping', '');
         $recorder->addConfig('keycloak.logoutRedirectUrl', '');
 
         // Recent news widget

phpmyfaq/translations/language_de.php

@@ -1702,6 +1702,8 @@
 $LANG_CONF['keycloak.redirectUri'] = ['input', 'Redirect-URI', 'Im Keycloak-Client registrierte Callback-URL'];
 $LANG_CONF['keycloak.scopes'] = ['input', 'Scopes', 'Leerzeichengetrennte Scopes, z.B. openid profile email'];
 $LANG_CONF['keycloak.autoProvision'] = ['checkbox', 'phpMyFAQ-Benutzer beim ersten Keycloak-Login automatisch anlegen'];
+$LANG_CONF['keycloak.groupAutoAssign'] = ['checkbox', 'phpMyFAQ-Gruppen automatisch aus Keycloak-Rollen zuweisen'];
+$LANG_CONF['keycloak.groupMapping'] = ['input', 'Rollen-zu-Gruppen-Zuordnung', 'JSON-Objekt zur Abbildung von Keycloak-Rollen auf phpMyFAQ-Gruppennamen, z.B. {"admin":"Administratoren"}'];
 $LANG_CONF['keycloak.logoutRedirectUrl'] = ['input', 'Logout-Redirect-URL', 'URL für die Weiterleitung nach dem Keycloak-Logout'];
 
 $LANG_CONF['mail.provider'] = ['select', 'E-Mail-Anbieter'];

phpmyfaq/translations/language_en.php

@@ -1694,6 +1694,8 @@
 $LANG_CONF['keycloak.redirectUri'] = ['input', 'Redirect URI', 'Callback URL registered in the Keycloak client'];
 $LANG_CONF['keycloak.scopes'] = ['input', 'Scopes', 'Space-separated scopes, e.g. openid profile email'];
 $LANG_CONF['keycloak.autoProvision'] = ['checkbox', 'Automatically create phpMyFAQ users on first Keycloak login'];
+$LANG_CONF['keycloak.groupAutoAssign'] = ['checkbox', 'Automatically assign phpMyFAQ groups from Keycloak roles'];
+$LANG_CONF['keycloak.groupMapping'] = ['input', 'Role to group mapping', 'JSON object mapping Keycloak roles to phpMyFAQ group names, e.g. {"admin":"Administrators"}'];
 $LANG_CONF['keycloak.logoutRedirectUrl'] = ['input', 'Logout redirect URL', 'URL to redirect to after Keycloak logout'];
 
 $LANG_CONF['mail.provider'] = ['select', 'Mail provider'];