This extension equips Flarum with Single Sign On (shortly SSO). Basically, this extension will act as a bridge between Flarum and your SSO/Auth system. The extension is useful if you run Flarum on a subdomain but you want to use the login mechanism of your main website.
If you have an OpenID Connect provider/auth system you can use my OpenID Connect Client Extension, that requires zero coding from your side. You only have to configure it and you’re ready to go!
¶ Requirements
- PHP 7.3+
- PHP JSON extension enabled
- The following PHP extensions installed and enabled if you want to use JWT features (premium):
- Hash
- Mbstring
- OpenSSL
- Sodium
¶ How does it work?
Workflow based on this post.
The user wants to login to your Auth system. Once his login attempt is successful, a POST request is sent to Flarum API from one of the extension plugins to retrieve the user access token (verifying his credentials). He will be created in the Flarum database (through an API request) if he isn’t signed up on Flarum.
Then, the access token is saved in a cookie to be used when the user visits Flarum (this cookie keeps the login active).
¶ Extension, Plugins & Addons
This section covers the difference between plugins and addons.
¶ Extension
This is the standard Flarum extension, installable on Flarum following the Installation instructions. This is required since it activates the user when he is added to the database, manage his logout, changes the Login and Signup links destination, …
¶ Plugins
A plugin is a library/package that you install on your Auth system to communicate with Flarum. This allows you to login, signup, update or logout the user (these are only examples, there may be other features along these ones). Some plugins are already developed for you and needs only to add the proper settings, like the WordPress plugin.
Examples of plugins are the PHP and WordPress ones. You can find them in the “Plugins” section in the left sidebar.
¶ Addons
Addons are additional features that can be added to the plugin(s). The installation method changes with the plugin you are using. For example, with the PHP plugin you have to add an addon calling an object method, while on WordPress you need to install it through the plugins screen.
Examples of addons are the Groups and the JWT ones.
¶ Installation
Install by executing the command below and activate the extension in Flarum Administration area.
composer require maicol07/flarum-ext-sso
You’ll also need a plugin to get it work with your auth system. You can choose one from the “Plugins” section in the left sidebar.
¶ ⚠️ PHP versions support/drop notice
PHP versions will be supported until its EOL.
If Flarum core changes PHP version before the official EOL, I’ll update too the version accordingly to what they have chosen.
¶ Upgrading
Upgrade by executing the command below, like with every other extension.
composer update maicol07/flarum-ext-sso
¶ Configuration
Here is the explanation of all the extension settings:
-
Signup URL: URL where the user will be redirected when the Signup button is clicked
-
Login URL: URL where the user will be redirected when the Login button is clicked
-
Logout URL: URL where the user will be redirected when the Logout button is clicked
-
Manage account URL (available in 1.8+): URL where the user will be redirected whenthe Manage Account button is clicked. This button shows up in the user settings only if this setting has a valid URL.
-
Open account management in a new tab (available in 1.8+): Open the link of the Manage Account button in a new tab
-
Remove login button: Removes the login button from Flarum frontend
-
Remove signup button: Removes the signup button from Flarum frontend
-
Cookies name prefix: Prefix of the token cookie. Set by default to “flarum”
-
Provider mode: Enable this option to use the provider mode (SSO between Flarum instances).
Allows other Flarum instances to login an user of this Flarum instance.
This will disable the standard SSO feature with other websites.
Default values for WordPress are:
- Signup url:
https://example.com/wp-login.php?action=register - Login url:
https://example.com/wp-login.php?redirect_to=forum(Theredirect_to=forumpart is important as it will redirect your users back to the forum) - Logout url:
https://example.com/wp-login.php?action=logout
¶ Addons related settings
¶ JWT Addon
- Issuer domain: The
issclaim of your JWT. This is the domain that issues the JWT. Typically, this corresponds with the root domain. - Signing algorithm: Algorithm used in the JWT addon to sign the token.
- Signer key: The base64 encoded signer key of your JWT. You can generate one with this tool: Cryptokey
¶ ⚠️ Package required
This addon requires the lcobucci/jwt:>=4.1 package added (and installed) to Flarum composer.json to work.
¶ Provider mode
Sponsored by @kuaza from https://sorucevap.com
You can enable provider mode to register Flarum instances as clients and login users with your provider Flarum account.
To do so, you must obtain an API key and a password token for each Flarum client you want to add (check in the PHP plugin options how to obtain them).
Then you have to enable the “Provider mode” in the main flarum instance you want to be the provider and register clients with their parameters:
- Name: Name of the client Flarum instance
- URL: URL of the client Flarum instance
- API Key: URL of the client Flarum instance (refer to the PHP plugin instructions)
- Password token: Password token of the client Flarum instance (refer to the PHP plugin instructions)
- Verify SSL: Verify the SSL certificate of the client Flarum instance when making requests to it.
In the client Flarum you have to set it up normally, but you have to set the Cookie prefix setting this way: if the client name is filled in provider, then the cookie prefix is the client name, otherwise it will be equal to the value of the URL field of the client.
Beware that using a client name that contains spaces or special characters might cause problems when an user tries to login!
¶ Links
¶ Changelog
Major changes are marked with 
¶ 1.11.5
Released on March 10, 2023
¶ 🐛 Bug Fixes
-
2795bce🐛 Fix wrong event type when deleting an user¶ 📝 Docs changes
-
7fd176c📝 Removed bazaar references¶ Other changes
-
91a8e68🙈 Added composer.lock in .gitignore¶ ⏪ Reverts
-
b109334chore: Added composer.lockThis reverts commit d389a1c5df684b1a55bfba9bbad4d97f4afd6b28.
¶ 1.11.4
Released on December 13, 2022
¶ ⚡ Performance Improvements
f074256⚡ Improved responsiveness of settings page
¶ 🐛 Bug Fixes
¶ Other changes
¶ 1.11.3
Released on November 16, 2022
¶ 🐛 Bug Fixes
de71fb1Re-added missing Logout URL setting
¶ 1.11.2
Released on October 26, 2022
¶ ✨ Features
-
8ea8f8f✨ Fix login redirects in embeded mode¶ 🔀 Pull Requests
-
da54638Merge pull request #17 from ruslanbelziuk/embed_support
¶ 1.11.1
Released on October 21, 2022
¶ 🐛 Bug Fixes
aa58e2b🐛 logout middleware redirect
¶ 🔀 Pull Requests
¶ 1.11
Released on October 02, 2022
¶ ✨ Features
-
2d7f772✨ Added provider modeSponsored by @kuaza from https://sorucevap.com -
a15b3e9✨ Added settings page
¶ 🐛 Bug Fixes
d10faf5Fix method deprecation
¶ ♻ Code Refactoring
¶ 👷 CI changes
-
4674f1bRemoved build actionAlready included in frontend -
bdf9671💚 Fix JS build action -
699ec7fDisable TS checks -
d771657Added backend action -
ff8df07Improved changelog generation
¶ Other changes
990e838Updated JS to TS, CI and config to latest updatedc62612deps: ⬆️ Upgraded dependenciesea3861bdeps: ⬆️ Updated dependencies9a233fbdeps: ⬆️ Updated dependenciesbec87c5deps: Added bundlewatch
¶ 1.10.3
Released on October 21, 2021
¶ 🐛 Bug Fixes
-
5b7afa3Unblock other extensions routesIt was impossible for other extensions, loaded after SSO to register new routes
-
ecc0676Signup button points to logout URL
¶ 1.10.2
Released on August 09, 2021
¶ ✨ Features
fd9bc60✨ Added Typescript config to get Flarum typing definitions8b70076code_tools: ✨ Added Prettier instead of ESLint
¶ ⚡ Performance Improvements
6fbd7f9⚡ Better frontend settings helper
¶ 🐛 Bug Fixes
3e24b49New Discussion button opening the Login modal- Also did some major refactor
f9cb9f4🐛 Wrong app namespace
¶ ♻ Code Refactoring
3dce5dcReformatted build actionedbd507♻️ Removed old Webpack configf17a9a5♻️ Removed ESLint comments
¶ 👷 CI changes
3233f94Trigger changelog workflow when JS build has finishedf244d0fUpdated build actionb8e32e2👷 Added Flarum Bot to automatically compile JS646203c👷 Added conditional commit messages to changelog action086bdea👷 Updated changelog generation
¶ Other changes
4145636deps: ⬆️ Upgraded Flarum Webpack config3e99300meta: Updated extension icon colors for better contrast
¶ 1.10.1
Released on June 12, 2021
¶ ⚡ Performance Improvements
b74c90c⚡ Use dot notation to set array value
¶ 🐛 Bug Fixes
¶ 📝 Docs changes
5e84bf4📝 Fixed PHPDocs
¶ 👷 Building scripts changes
8f3d699Allow to run changelog action manually to set the next version5cb1154Add git credentialsa10765eAdd missing commitc009c2eAdd missing token to push back changes8ab1c6fPush CHANGELOG.md back to repob705c4fEnsure changelog is saved to fileec11208Fix changelog action branch801fc90Missing checkout action
¶ Other changes
69b9e7eAdded more author metadata tocomposer.jsonfcd76e6Added flarum version support badge5de2a76deps: Moved JWT package to suggestions7a4ce8clocale: Delete pl.yml (#11)
¶ 1.10
Released on May 22, 2021
¶ ✨ Features
¶ 1.9
Released on April 08, 2021
¶ 
Features
6c802df Allow updating user avatar via avatarUrlattributebc56ed3 New Login middleware3e033f8 Initial compatibility with beta16
¶ 
Bug Fixes
830def6 Exception when updating user and avatarUrlisnull978e1de Fixed issue with the Laravel Cookie helper
¶ 
Performance Improvements
3cf884f Improved subscribers and listeners handling
¶ 🔄 Updates
27b284e
Updated JWT SSO to beta16
Major changes:- 💥 Signer key must be plain text now. It will be encoded to base64 automatically
- 💥 Login is no longer done with the login method (which is now named getToken) but will rely on the new middleware
¶ 👷 Building scripts changes
¶ Other changes
¶ 1.8.1 (2021-01-24)
¶ 
Added
- Added JWT Signing Algorithm option
¶ Changed
- Migrated to lcobucci/jwt v4 (compatible with v3.4.2 if already installed)
¶ 1.8 - Beta 15 support (2020-12-23)
¶ Added
Added support for Beta 15 (now the extension requires beta 15 to run)
New settings page- Added Manage Account button in user settings
¶ Improvements
- Improved code and removed outdated one
¶ 
Fixed
- Fixed login modal showing up when user is not logged in and clicks the Start discussion button (PR #7)
- Login modal not showing when extension is enabled but no login url is set
¶ 1.7 - Beta 14 support (2020-11-02)
¶ Added
- Added support to Beta 14 (now the extension requires beta 14 to run)
Compatibility with Json Web Tokens
¶ 
Improvements
Revamped docs
¶ Fixed
- Fixed logout (#FSSOE-1)
¶ 1.6 - Beta 13 support (2020-05-13)
- Beta 13 support
¶ 1.5 (2020-04-08)
- Moved plugins into its own repos
¶ 1.4.6 (2020-03-09)
- Allow installation on beta 12
¶ 1.4.4 (2020-02-05) & 1.4.5 (2020-02-06)
- Fixed settings modal not showing up
¶ 1.4.3 (2020-01-20)
- Fix for version constaint
¶ 1.4.1 & 1.4.2 (2020-01-05)
- Critical fix to solve crash at Flarum startup
- Extension settings modal construction moved to @fof/components (thanks to @datitisev for its lib)
- Code enhancements
¶ 1.4.0 (2020-01-05)
- Added “Remove signup and login button” option in settings
- SSO won’t work if a URL isn’t set
- Fixed and changed icon
¶ 1.3.2 (2019-10-16)
- Fixed a critical issue that caused the extension not to work
- Updated sample website example
¶ 1.3.1 (2019-10-14)
- Minor tweak to
composer.json
¶ 1.3.0 (2019-10-13)
- Added new
deletemethod (not fully tested, but should working almost all the times) - Added new
getFlarumLinkmethod that returns flarum link set inconfig.phpfile - Added detailed comments in every method
- Added Italian translation
- Changed Curl requests with HTTP requests (Curl failed all the times with my tests)
- Minor tweaks and enhancements
¶ 1.2.0
- Compatibility with beta 8.1
- Added Polish language
¶ 1.1.2 (2017-08-09)
- Removed account section from settings
¶ 1.1.1 (2017-07-09)
- Login redirect
¶ 1.1.0 (2017-03-29)
- Added WordPress plugin
¶ 1.0.1 (2017-03-11)
- Added token lifetime to config
- Extended token lifetime
¶ 1.0 (2017-03-01)
- First version