This guide explains how to set up Flarum with the required dependencies for seamless JWT-based Single Sign-On integration with Joomla.

The integration uses the mature maicol07/flarum-ext-sso extension with JWT authentication to provide secure, enterprise-grade SSO between Joomla and Flarum.

• PHP: 8.2+ (same as Joomla 5)
• Composer: Latest version
• Web Server: Apache/Nginx with HTTPS support
• Database: MySQL 5.7+ or MariaDB 10.3+

• Flarum: 1.8.10+ (tested and working)

If you haven’t installed Flarum yet:

# Create Flarum installation directory
mkdir /var/www/forum.yoursite.com
cd /var/www/forum.yoursite.com
 
# Install Flarum
composer create-project flarum/flarum .
 
# Set proper permissions
chmod 775 storage/
chmod -R 775 storage/
chown -R www-data:www-data storage/

Complete the web installer by visiting your forum URL.

⚠️ CRITICAL: Admin User Email Requirement

During Flarum installation, you MUST use the same email address for the Flarum admin user as your Joomla admin user.

Why this matters: - Once SSO is enabled, you cannot log into Flarum directly - You are completely reliant on the SSO plugin working - The plugin matches users by email address - If emails don’t match, admin cannot access the forum

Example: - ✅ Correct: Joomla admin = admin@yoursite.com, Flarum admin = admin@yoursite.com - ❌ Wrong: Joomla admin = admin@yoursite.com, Flarum admin = martin@yourcompany.com

If you already installed Flarum with different admin email: 1. Go to Flarum admin panel (before enabling SSO) 2. Update admin user email to match Joomla admin email 3. Save changes 4. Then proceed with SSO setup

You can install new extensions as the Flarum administrator, using the Extension Manager. Or you can add them in a terminal as follows.

cd /var/www/forum.yoursite.com
composer require maicol07/flarum-ext-sso

During our testing, we discovered that the lcobucci/clock library is required but not automatically installed:

# Install the missing clock library
composer require lcobucci/clock

This fixes the “Class Lcobuccinot found” error.

You can enable the SSO extension in the administrator’s Extension Manager by selecting SSO extension and clicking the toggle for enable. Or in a terminal:

# Enable the SSO extension
php flarum extension:enable maicol07-sso

1. Log into your Flarum forum as an administrator
2. Go to Admin → Extensions → SSO (by maicol07)

You will need a JWT key. This can be any long, random string. We use an example here. You will need to use the same key in Flarum and in the Joomla plugin. Adjust the URLs below to suit your site.

Set the following configuration:

JWT Issuer (jwt_iss): yoursite.com
JWT Signing Algorithm: Sha256
JWT Signer Key: c1Y9I+cYf8x5p4pxJDZj7GuAgoi/0ueAn2WC2D+3WYs=
Login URL: https://yoursite.com/component/users/login
Logout URL: https://yoursite.com/component/users/login
Signup URL: https://yoursite.com/component/users/registration
Manage Account URL: https://yoursite.com

Important Notes: - JWT Signer Key: Must match exactly with the Joomla plugin configuration - JWT Issuer: Should be your main domain without https:// (e.g., yoursite.com) - URLs: Point back to your Joomla site for user management

cd /var/www/forum.yoursite.com
php flarum info

You should see maicol07-sso listed in the enabled extensions.

Test that the JWT endpoint is working:

# This should return a 400 error (expected - no Authorization header)
curl -I https://forum.yoursite.com/api/sso/jwt

Expected response: 400 Bad Request (this means the endpoint exists)

Verify all dependencies are installed:

composer show lcobucci/jwt lcobucci/clock

Both should show as installed.

If using forum.yoursite.com:

1. DNS: Point forum.yoursite.com to your server
2. SSL: Ensure HTTPS certificate covers both domains
3. Cookie Domain: The plugin will set cookies for .yoursite.com to enable cross-subdomain authentication

This is likely to prove more difficult than using a subdomain, but should be possible.

If using yoursite.com/forum:

1. Configure web server to serve Flarum from /forum path
2. Update Flarum’s config.php with correct URL
3. Ensure proper URL rewriting rules

1. Generate JWT: Log into Joomla and test the JWT generation endpoint
2. Verify Token: Check that Flarum accepts the JWT token
3. Test SSO: Use the forum redirect URL to test automatic login

403 Permission Denied: - Check JWT signer key matches between Joomla and Flarum - Verify JWT issuer configuration - Check user exists in both systems

500 Internal Server Error: - Install missing lcobucci/clock dependency - Check Flarum error logs: /var/www/forum.yoursite.com/storage/logs/

404 Not Found: - Verify SSO extension is enabled - Check web server configuration - Ensure mod_rewrite is working

<?php return array (
  'debug' => false,
  'database' => 
  array (
    'driver' => 'mysql',
    'host' => 'localhost',
    'port' => 3306,
    'database' => 'flarum_db',
    'username' => 'flarum_user',
    'password' => 'secure_password',
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix' => 'flarum_',
    'strict' => false,
    'engine' => 'InnoDB',
    'prefix_indexes' => true,
  ),
  'url' => 'https://forum.yoursite.com',
  'paths' => 
  array (
    'api' => 'api',
    'admin' => 'admin',
  ),
);

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.php [QSA,L]
</IfModule>

server {
    listen 80;
    server_name forum.yoursite.com;
    return 301 https://$server_name$request_uri;
}
 
server {
    listen 443 ssl http2;
    server_name forum.yoursite.com;
    root /var/www/forum.yoursite.com/public;
    index index.php;
 
    # SSL configuration
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
 
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
 
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
 
    location ~* \.(?:css|js|gif|png|jpg|jpeg|webp|svg|woff|woff2|ttf|eot|ico)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

1. Strong Keys: Use cryptographically secure signing keys (64+ characters)
2. Short Expiry: JWT tokens expire in 5 minutes for security
3. HTTPS Only: Never use HTTP for authentication
4. Key Rotation: Consider periodic key rotation for high-security environments

1. Separate User: Create dedicated database user for Flarum
2. Minimal Permissions: Grant only required database permissions
3. Connection Encryption: Use SSL for database connections if possible

# Secure file permissions
find /var/www/forum.yoursite.com -type d -exec chmod 755 {} \;
find /var/www/forum.yoursite.com -type f -exec chmod 644 {} \;
chmod 775 /var/www/forum.yoursite.com/storage
chmod -R 775 /var/www/forum.yoursite.com/storage/
chown -R www-data:www-data /var/www/forum.yoursite.com/

You can achieve higher security if using PHP-FPM where each site can have its own user. In this case, you can use 750 and 640 for permissions, which will isolate sites from one another.

cd /var/www/forum.yoursite.com
composer update maicol07/flarum-ext-sso
composer update lcobucci/clock lcobucci/jwt

Regular monitoring of Flarum logs:

tail -f /var/www/forum.yoursite.com/storage/logs/flarum-$(date +%Y-%m-%d).log

Include in your backup routine: - Flarum database - Flarum files (especially config.php) - Extension configurations - Custom themes/assets

“Class Lcobuccinot found”:

composer require lcobucci/clock

“Signature key does not correspond to the one on the token”: - Check JWT signing key matches in both Joomla plugin and Flarum SSO extension

“User not found”: - Enable user auto-creation in Joomla plugin - Check user synchronization settings

Enable Flarum debug mode temporarily:

// In config.php
'debug' => true,

Remember to disable debug mode in production!

; php.ini optimizations
opcache.enable=1
opcache.memory_consumption=512
opcache.max_accelerated_files=65407
opcache.validate_timestamps=0  ; Production only
opcache.save_comments=1
opcache.fast_shutdown=1

-- Optimize Flarum tables
OPTIMIZE TABLE flarum_users;
OPTIMIZE TABLE flarum_posts;
OPTIMIZE TABLE flarum_discussions;

This setup provides a robust, secure JWT-based SSO integration between Joomla and Flarum. The configuration is production-ready and follows security best practices.

For support or issues, refer to: - maicol07/flarum-ext-sso documentation - Flarum Community - Plugin author: martin@remository.com