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

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.

# 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)

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

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/

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