README

A Flarum extension that provides Single Sign-On (SSO) authentication using JWT tokens from your main site.

Features

JWT-based authentication flow
Automatic user creation and updates
Secure token validation
CSRF protection with state parameters
Configurable user group assignment
Optional override of default Flarum login
Comprehensive error handling

Installation

Install via Composer:

composer require aditya-wiguna/flarum-jwt-sso

Enable the extension:

php flarum extension:enable aditya-wiguna-flarum-jwt-sso

Run migrations:

php flarum migrate

Configure the extension in your Flarum admin panel.

Configuration

Admin Panel Settings

Main Site URL: Base URL of your authentication site
Login URL: URL where users are redirected for authentication
Logout URL: URL where users are redirected after logout (optional)
JWT Secret Key: Secret key used to verify JWT tokens
JWT Issuer: Expected issuer claim in tokens (optional)
Default Groups: Comma-separated group IDs for new users
Override Login: Replace Flarum's default login with SSO only

Environment Variables (Recommended)

JWT_SSO_SECRET_KEY=your-secret-key-here
JWT_SSO_MAIN_SITE_URL=https://your-site.com
JWT_SSO_LOGIN_URL=https://your-site.com/auth/flarum
JWT_SSO_LOGOUT_URL=https://your-site.com/logout
JWT_SSO_ISSUER=your-domain.com

Authentication Flow

User clicks login in Flarum
User is redirected to your main site with state parameter
User authenticates on your main site
Your main site redirects back to Flarum with JWT token
Flarum validates the JWT and creates/updates the user
User is logged into Flarum

JWT Token Requirements

Your main site must return a JWT token with these claims:

Required Claims

sub: User ID in your system
email: User's email address
exp: Token expiration timestamp

Optional Claims

iss: Token issuer (validated if configured)
username: Preferred username
name or display_name: User's display name
avatar_url: User's profile picture URL
iat: Token issued at timestamp

Example JWT Payload

{
  "iss": "your-domain.com",
  "sub": "12345",
  "email": "user@example.com",
  "username": "johndoe",
  "name": "John Doe",
  "avatar_url": "https://example.com/avatar.jpg",
  "iat": 1640995200,
  "exp": 1640998800
}

Main Site Integration

Redirect URL Structure

Your login URL should accept these parameters:

return_url: Where to redirect after authentication
state: CSRF protection token

Response URL Structure

After authentication, redirect to the return_url with:

token: The JWT token
state: The original state parameter
error: Error message (if authentication failed)

Example Implementation (PHP)

// Handle Flarum authentication request
if (isset($_GET['return_url']) && isset($_GET['state'])) {
    $returnUrl = $_GET['return_url'];
    $state = $_GET['state'];
    
    // Authenticate user (your existing logic)
    if ($user->isAuthenticated()) {
        // Generate JWT token
        $payload = [
            'iss' => 'your-domain.com',
            'sub' => $user->id,
            'email' => $user->email,
            'username' => $user->username,
            'name' => $user->display_name,
            'avatar_url' => $user->avatar_url,
            'iat' => time(),
            'exp' => time() + 3600 // 1 hour
        ];
        
        $jwt = JWT::encode($payload, $secretKey, 'HS256');
        
        // Redirect back to Flarum
        $redirectUrl = $returnUrl . '?' . http_build_query([
            'token' => $jwt,
            'state' => $state
        ]);
        
        header('Location: ' . $redirectUrl);
        exit;
    } else {
        // Authentication failed
        $redirectUrl = $returnUrl . '?' . http_build_query([
            'error' => 'authentication_failed',
            'state' => $state
        ]);
        
        header('Location: ' . $redirectUrl);
        exit;
    }
}

API Endpoints

The extension creates these routes:

GET /auth/sso/login - Initiates SSO login flow
GET /auth/sso/callback - Handles authentication callback
POST /auth/sso/logout - Handles SSO logout

Troubleshooting

Common Issues

"SSO configuration is incomplete"
- Ensure Main Site URL and Login URL are configured
- Check that settings are saved properly
"Invalid token signature"
- Verify the JWT secret key matches between systems
- Ensure both systems use the same algorithm (HS256)
"Token has expired"
- Check token expiration time on your main site
- Ensure system clocks are synchronized
"Invalid state parameter"
- Session storage issues
- CSRF protection triggered
- Clear browser cache and try again

Debug Mode

Enable debug logging by adding this to your main site:

// Log JWT payload before encoding
error_log('JWT Payload: ' . json_encode($payload));

// Log generated token
error_log('Generated JWT: ' . substr($jwt, 0, 50) . '...');

Security Considerations

Always use HTTPS in production
Use strong, random JWT secret keys
Implement short token expiration times
Monitor authentication logs
See SECURITY.md for detailed security guidelines

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This extension is licensed under the MIT License.

Support

Create an issue on GitHub for bug reports
Check existing issues before creating new ones
Provide detailed information about your setup

aditya-wiguna / flarum-jwt-sso

Maintainers

Details