edit this page

Single Sign On (from Github)

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

Prerequisites

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

Step 1: Configure Flarum SSO Extension

Follow the Flarum Setup Guide to:

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

Step 2: Configure Joomla Plugin

In Joomla admin:

Go to //Extensions → Plugins → User - Flarum//
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 Configuration Example

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.

Step 3: Set Up Menu Link

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

Go to //Menus → Menu Items → New//
Set //Menu Item Type to External URL//

Use this URL format:

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

How JWT SSO Works

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

JWT Token Structure

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
}

Cross-Domain Setup

Subdomain Configuration (Recommended)

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

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

Different Domain Configuration

⚠️ //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//:

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

//Solution for users//:

Click //"Forgot Password?"// on Flarum login page
Enter your email address (same as Joomla account)
Check email and follow password reset link
Set your own Flarum password
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.

Testing the Integration

//Test Menu Access//:
Log into Joomla
Click the forum menu item
You should be automatically logged into Flarum
//Test User Creation//:
Create a new user in Joomla
Have them click the forum link
They should be automatically created in Flarum
//Test Logout//:
Log out of Joomla
Visit Flarum directly - you should be logged out

Troubleshooting

Common Issues

//"Access denied - admin permissions required"//:
Ensure forumRedirect is in the plugin's $publicMethods array
Check plugin is properly enabled
//"Class Lcobucci\Clock\SystemClock not found"//:
Install missing dependency: composer require lcobucci/clock
Run in Flarum directory
//"Signature key does not correspond"//:
Verify JWT signer key matches exactly in both systems
Check key encoding and format
//Cross-domain authentication fails//:
Ensure both domains use HTTPS
Check cookie domain settings
Verify subdomain DNS configuration
//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

Debug Information

Enable plugin logging to see detailed JWT operations:

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

Testing JWT Endpoint

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

Security Considerations

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

Advantages of JWT SSO

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