This guide explains how to configure the JWT-based Single Sign-On (SSO) between Joomla and Flarum using the maicol07/flarum-ext-sso extension.

1. Joomla Plugin: This Flarum Integration plugin installed and configured
2. Flarum SSO Extension: maicol07/flarum-ext-sso extension installed and configured
3. Dependencies: lcobucci/clock library installed in Flarum
4. API Access: Working Flarum API connection

Follow the Flarum Setup Guide to:

1. Install composer require maicol07/flarum-ext-sso
2. Install composer require lcobucci/clock
3. Enable the extension: php flarum extension:enable maicol07-sso
4. Configure the SSO settings in Flarum admin panel

In Joomla admin:

1. Go to Extensions → Plugins → User - Flarum
2. Configure the JWT SSO Settings:

• JWT Issuer: Your domain (e.g., remository.com)
• JWT Signing Algorithm: Sha256
• JWT Signer Key: Must match Flarum configuration exactly
• JWT Audience: Your Flarum URL (e.g., https://forum.remository.com)

JWT Issuer: remository.com
JWT Signing Algorithm: Sha256
JWT Signer Key: c1Y9I+cYf8x5p4pxJDZj7GuAgoi/0ueAn2WC2D+3WYs=
JWT Audience: https://forum.remository.com

⚠️ Important: The JWT Signer Key must match exactly between Joomla and Flarum configurations.

Create a menu item in Joomla that links to the forum with automatic authentication:

1. Go to Menus → Menu Items → New
2. Set Menu Item Type to External URL
3. Use this URL format:

   https://yoursite.com/index.php?option=com_ajax&plugin=flarum&group=user&method=forumRedirect&format=raw
   

1. User clicks forum menu: Redirects to the forumRedirect method
2. Authentication check: Plugin checks if user is logged into Joomla
3. User creation: If user doesn't exist in Flarum, automatically creates them
4. JWT generation: Creates fresh JWT token with 5-minute expiry
5. Flarum authentication: Sends JWT to Flarum SSO endpoint
6. Cookie setting: Sets authentication cookie for subdomain access
7. Forum redirect: User is redirected to Flarum, automatically logged in

The plugin generates JWT tokens with these claims:

{
  "iss": "remository.com",
  "aud": "https://forum.remository.com", 
  "jti": "3",
  "sub": "3",
  "iat": 1640995200,
  "exp": 1640995500,
  "user": {
    "id": 3,
    "type": "users",
    "attributes": {
      "username": "johndoe",
      "displayName": "John Doe",
      "email": "john@example.com"
    }
  },
  "remember": false
}

For subdomain configurations (e.g., forum.yoursite.com):

1. DNS: Point forum subdomain to your server
2. SSL: Ensure HTTPS certificate covers both domains
   
3. Cookie Domain: Plugin automatically sets cookies for parent domain (.yoursite.com)
4. Result: ✅ Automatic login works perfectly

⚠️ Important Limitation: If you cannot use a subdomain setup (e.g., forum on completely different domain), automatic login will not work due to cross-domain cookie restrictions.

What happens:

1. User clicks forum menu link in Joomla
2. Plugin creates Flarum account automatically (with random password)
3. User is redirected to Flarum but not logged in
4. User sees Flarum login page

Solution for users:

1. Click “Forgot Password?” on Flarum login page
2. Enter your email address (same as Joomla account)
3. Check email and follow password reset link
4. Set your own Flarum password
5. Future logins use your chosen Flarum password

Why this happens: The plugin cannot share your Joomla password with Flarum for security reasons, and creates Flarum accounts with random passwords that only the system knows.

1. Test Menu Access:

• Log into Joomla
• Click the forum menu item
• You should be automatically logged into Flarum

1. Test User Creation:

• Create a new user in Joomla
• Have them click the forum link
• They should be automatically created in Flarum

1. Test Logout:

• Log out of Joomla
• Visit Flarum directly - you should be logged out

1. “Access denied - admin permissions required”:

• Ensure forumRedirect is in the plugin's $publicMethods array
• Check plugin is properly enabled

1. “Class Lcobucci\Clock\SystemClock not found”:

• Install missing dependency: composer require lcobucci/clock
• Run in Flarum directory

1. “Signature key does not correspond”:

• Verify JWT signer key matches exactly in both systems
• Check key encoding and format

1. Cross-domain authentication fails:

• Ensure both domains use HTTPS
• Check cookie domain settings
• Verify subdomain DNS configuration

1. User redirected to forum but not logged in:

• This is expected behavior for different domain setups
• User account is created automatically but login requires password reset
• Instruct users to use “Forgot Password?” with their email address
• See “Different Domain Configuration” section above for complete steps

Enable plugin logging to see detailed JWT operations:

1. Set plugin to debug mode
2. Check custom log file for JWT generation details
3. Monitor Flarum logs: /storage/logs/flarum-YYYY-MM-DD.log

Test that Flarum SSO endpoint is working:

====== Should return 400 Bad Request (expected without Authorization header) ======
curl -I https://forum.yoursite.com/api/sso/jwt

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 Management: Store JWT keys securely in plugin configuration

• ✅ Secure: Uses industry-standard JWT tokens
• ✅ Mature: Built on established maicol07/flarum-ext-sso extension
• ✅ Scalable: Handles high-traffic scenarios
• ✅ On-Demand: Generates fresh tokens for each access
• ✅ Cross-Domain: Works with subdomain configurations

• Flarum Setup Guide - Complete Flarum installation
• README.md - Plugin overview and features
• maicol07/flarum-ext-sso - Extension documentation