Documentation by Black Sheep Research

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Flarum Setup Guide for JWT-Based SSO Integration ======

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 ====

  * **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 Version ====

  * **Flarum**: 1.8.10+ (tested and working)

===== Step 1: Install Flarum =====

If you haven’t installed Flarum yet:

<code bash>
# 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/
</code>

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.

<code bash>
cd /var/www/forum.yoursite.com
composer require maicol07/flarum-ext-sso
</code>

==== Install Missing Dependencies ====

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

<code bash>
# Install the missing clock library
composer require lcobucci/clock
</code>

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:

<code bash>
# Enable the SSO extension
php flarum extension:enable maicol07-sso
</code>

===== Step 3: Configure Flarum SSO Extension =====

==== Access Flarum Admin Panel ====

  - Log into your Flarum forum as an administrator
  - 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:

<code>
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
</code>

**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 ====

<code bash>
cd /var/www/forum.yoursite.com
php flarum info
</code>

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

==== Test JWT Endpoint ====

Test that the JWT endpoint is working:

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

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

==== Check Required Libraries ====

Verify all dependencies are installed:

<code bash>
composer show lcobucci/jwt lcobucci/clock
</code>

Both should show as installed.

===== Step 5: Domain Configuration =====

==== For Subdomain Setup (Recommended) ====

If using ''%%forum.yoursite.com%%'':

  - **DNS**: Point forum.yoursite.com to your server
  - **SSL**: Ensure HTTPS certificate covers both domains
  - **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%%'':

  - Configure web server to serve Flarum from ''%%/forum%%'' path
  - Update Flarum’s ''%%config.php%%'' with correct URL
  - Ensure proper URL rewriting rules

===== Step 6: Integration Testing =====

==== Test JWT Authentication Flow ====

  - **Generate JWT**: Log into Joomla and test the JWT generation endpoint
  - **Verify Token**: Check that Flarum accepts the JWT token
  - **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 ====

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

==== Web Server Configuration ====

=== Apache .htaccess (already included with Flarum) ===

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

=== Nginx Configuration ===

<code nginx>
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";
    }
}
</code>

===== Security Considerations =====

==== JWT Security ====

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

==== Database Security ====

  - **Separate User**: Create dedicated database user for Flarum
  - **Minimal Permissions**: Grant only required database permissions
  - **Connection Encryption**: Use SSL for database connections if possible

==== File Permissions ====

<code bash>
# 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/
</code>

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 ====

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

==== Monitor Logs ====

Regular monitoring of Flarum logs:

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

==== 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”**:

<code bash>
composer require lcobucci/clock
</code>

**“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:

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

**Remember to disable debug mode in production!**

===== Performance Optimization =====

==== OpCache Configuration ====

<code ini>
; 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
</code>

==== Database Optimization ====

<code sql>
-- Optimize Flarum tables
OPTIMIZE TABLE flarum_users;
OPTIMIZE TABLE flarum_posts;
OPTIMIZE TABLE flarum_discussions;
</code>

===== 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: - [[https://github.com/maicol07/flarum-ext-sso|maicol07/flarum-ext-sso documentation]] - [[https://discuss.flarum.org|Flarum Community]] - Plugin author: martin@remository.com