Flarum Sso Plugin Laravel Package

Getting Started

This is a Flarum extension, not a Laravel package — it's installed into a Flarum installation (Flarum itself is built on Illuminate components, so the conventions will feel familiar). Don't try to composer require it into a Laravel app.

Minimal path:

1. In your Flarum root: composer require maicol07/flarum-sso-php-plugin
2. Enable it in the admin panel (Extensions → SSO), then open its settings.
3. Register your client credentials / endpoints with the SSO provider and paste them into the extension settings.
4. Clear caches after any settings change: php flarum cache:clear

Look first at:

• The extension's admin settings screen (the authoritative list of configurable options for your installed version).
• The example/ directory in the repo — it was touched in 3.3.2 and is the canonical reference for the login flow.
• Generated API docs on GitHub Pages (as of 3.3.2 these are no longer committed to the repo — see Gotchas).

First use case: delegating authentication to an external SSO/IdP so users log into Flarum with centrally-managed credentials, with accounts provisioned on first login from IdP claims (username, email, groups).

Implementation Patterns

• Laravel app as the IdP. The common setup is a Laravel app acting as the identity source, with Flarum as the relying party. Keep the redirect URI registered in your Laravel OAuth/SSO client byte-for-byte identical to what the extension sends.
• Attribute mapping is the integration surface. The 3.3.2 fix (set username attribute before login in the example) is a reminder that username must be resolved before the login call. If you adapt the example into your own flow, mirror that ordering — set username → set email → set groups → login.
• Group/role mapping. Map IdP groups to Flarum groups at provisioning time; treat group sync as a one-way projection from the IdP and decide explicitly whether it re-syncs on every login or only on creation.
• Keep customizations outside vendor. Use Flarum extenders and event listeners rather than editing the extension's source; the 3.3.2 refactor (rector rules, explicit nullable params) shows the internals churn between patches even when the public surface doesn't.
• Staging IdP first. Because the extension owns the login page, a misconfiguration locks you out of the admin panel. Keep a local admin/password fallback account and test against a staging IdP before cutting over.
• Upgrade cadence. Patches like 3.3.2 are safe to take promptly — they're cheap and keep you aligned with the PHP 8.4 nullability fixes.

Gotchas and Tips

• Not a Laravel package. No service provider, no config/*.php to publish, no artisan commands of its own. Configuration lives in Flarum's admin panel and database. Expecting php artisan vendor:publish is the most common wrong turn.
• PHP 8.4 nullable deprecations. 3.3.2 makes implicitly nullable parameters explicit, which matters if you're on PHP 8.4. The toolchain was retargeted to PHP 8.3 via Rector 2.x — verify your runtime against the extension's declared PHP constraint before upgrading, especially on 8.4.
• Asset paths changed. fonts.less / icons.less dropped the leading ../. If icons or fonts render broken after upgrading, recompile/publish assets and clear the cache (php flarum cache:clear, php flarum assets:publish) before debugging anything else — it's almost always stale compiled CSS.
• Docs moved. API docs are now published to GitHub Pages from Actions and are no longer in the repo. Deep links to docs/ in older issues or blog posts may 404; go to the Pages site for the current version.
• The example is illustrative. The 3.3.2 bug fix landed in example/, not in the extension's core — meaning the shipped example had a real flaw in login ordering. Read it as a reference, not as copy-paste production code.
• Debugging auth failures. Check storage/logs/ in the Flarum root first; most failures are redirect-URI mismatches, expired client secrets, or missing claims (username/email) from the IdP. Log the raw claim payload during setup, then remove that logging.
• Extension points. Flarum's event system and extenders are the stable surface; the extension's PHP classes are not a public API and the 3.3.2 refactor demonstrates they can be reshaped in a patch release.
• This release is low-risk. No breaking changes, no deprecations announced, no public API changes — a straightforward patch upgrade.