Setup

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

Overview

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

Requirements

System Requirements

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

Flarum Version

1. Flarum: 1.8.10+ (tested and working)

Step 1: Install Flarum

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

Step 2: Install Required Extensions

Install maicol07/flarum-ext-sso Extension

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

Install Missing Dependencies

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 Extension

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

Step 3: Configure Flarum SSO Extension

Access Flarum Admin Panel

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

Configure SSO Settings

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

Step 4: Verify Installation

Check Extension Status

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

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

Test JWT Endpoint

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)

Check Required Libraries

Verify all dependencies are installed:

composer show lcobucci/jwt lcobucci/clock

Both should show as installed.

Step 5: Domain Configuration

For Subdomain Setup (Recommended)

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

For Same Domain Setup

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

Step 6: Integration Testing

Test JWT Authentication Flow

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

Debug Common Issues

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

Configuration Files

Flarum config.php Example

<?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',
  ),
);

Web Server Configuration

Apache .htaccess (already included with Flarum)

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

Nginx Configuration

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";
    }
}

Security Considerations

JWT Security

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

Database Security

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

File Permissions

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

Maintenance

Keep Extensions Updated

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

Monitor Logs

Regular monitoring of Flarum logs:

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

Backup Strategy

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

Troubleshooting

Common Error Messages

“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

Debug Mode

Enable Flarum debug mode temporarily:

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

Remember to disable debug mode in production!

Performance Optimization

OpCache Configuration

; 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

Database Optimization

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

Conclusion

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