You need to create a random token (for security purposes it is better if this is long 40 characters, you can use this tool to make one) and put it into the
api_keys table of your Flarum database.
You only need to set the
key column and the
user_id one. In the first one write your new generated token and in the latter your admin user id.
The only supported way to install this plugin is through Composer:
composer require maicol07/flarum-sso-plugin
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.
Update composer packages as usual:
There may be some breaking changes in the update you are trying to install, so check the following version-specific upgrade notes to check how to handle these:
I suggest you to follow the examples in the example folder along with the following steps. API documentation can be found here or inside the
Basically, you need to do this:
use Maicol07\SSO\Flarum; $flarum = new Flarum($options);
$optionsis an associative array with the options listed below
use Maicol07\SSO\User; $user = $flarum->user($username) // Create the user object if it doesn't exists with the user method // Retrieve the user object with the user method **after** its creation $user_alias = $flarum->user(); // $user_alias contains the same object stored in $user
$usernameis a string (the username of the user)
$flarumis the Flarum object created in the previous step
$flarum_user->attributes->email = 'firstname.lastname@example.org'; $flarum_user->attributes->password = 'userpassword';
You can check other attributes in the API Docs or via your IDE autocompletion. Note that extensions may add other attributes that are not listed natively.
use Maicol07\Flarum\SSO\Addons\Groups; $flarum->loadAddon(Groups::class); $flarum->setAddonProperties(Groups::class, ['set_groups_admins' => true]); // if the addon has some attributes they can be added through this method $flarum_user->relationships->groups = ['group1', 'group2']
Like the attributes, there can be other relationships (that do not require an addon)
Here are explained the options of the plugin.
url- Flarum URL: This is the URL of your Flarum public folder (the URL where you can see your Flarum)
root_domain- Root domain: The domain of the root website (the SSO one, see here for exceptions)
api_key- API Key: The API key you have added in pre-installation steps.
password_token- Password Token: Just a random string to encrypt Flarum passwords (you can use this tool to generate one)
remember- Remember user: Optional. This is set by default to
false. It indicates if the token must be remembered across sessions or not (session periods are decided by Flarum. Currently they are 5 years with remembered session, else 1 hour renewable each time the user visits Flarum).
verify_ssl- Verify SSL: Optional. This is set by default to
true. Set this to
falseONLY if you don’t have an SSL certificate or you’re developing on your local server such as XAMPP. You can also set this to the path of an SSL certificate. More details on https://docs.guzzlephp.org/en/stable/request-options.html#verify.
cookies_prefix- Prefix for cookies name: String to prefix the cookie name when creating remember/auth tokens. Default: “flarum”
This addon is bundled into the plugin. So no installation required, only add it via the
loadAddon method and set its attribuetes, if required.
Feature: Sync groups of your Auth system with Flarum.
This addon is premium, which means that requires an active subscription to be used.
Feature: Use JWT (Json Web Token) instead of standard API Auth in order to gain more security during the authentication procedure.
key: Random base64 encoded key to sign the JWT. You can generate one with this tool: Cryptokey
signer: Algorithm used to sign the JWT. This can be an object of any of the algorithm classes defined under the
Lcobucci\JWT\Signer\Hmacnamespace. Some accepted classes examples:
Lcobucci\JWT\Signer\Hmac\Sha256(default; fastest on x86 system)
Lcobucci\JWT\Signer\Hmac\Sha512(stronger, fastest on x64 systems, slower on x86 ones)
You can pay with your preferred gateway.
|Price||2,99 €||2,99 €|
|Total Price||3,15 €||3,29 €|
|Payment buttons||Pay with Stripe|
Before buying read the Pricing notes!
Buying an addon includes proritary support via chat (1h/year) and proritary feature requests (1/year). The addon is valid only for one website (if you want to use this for multiple websites, you have to buy it again). Buying an addon multiple times will allow you to sum the addon features (for example, you buy 2 times an addon: you will be able to install the addon on two websites and you will get 2 hours/year of prioritary support via chat and 2 proritary feature requests/year)
If you want to cancel the subscription you can do it via your PayPal account if you paid with PayPal. Otherwise, check if there is an unsubscribe link in your stripe subscription confirmation email or contact the developer from his website (chat in the bottom-right corner or contact form)
If you have an SSO system located on a subdomain (for example account.example.com) and your Flarum installed on another subdomain (
forum.example.com) you must set the
root_domain option to the root domain (example.com), not the subdomain (account.example.com). While this is possible, it’s not possible to get this extension working on two different domains (example.com, example2.com) due to cookies limitation (see here for more info)
Do these checks (in order):
maicol07/flarum-ext-ssomust be installed in Flarum
maicol07/flarum_sso_pluginmust be installed in your auth system
Check if there is the
flarum_token cookie in your Flarum cookies. If yes, then check the first step (if not already done) and proceed to the next step. If not, you probably have set something wrong in your config/options.
Check if your user credentials rules are compatible with Flarum ones. Detailed rules are listed in this issue: https://tracker.maicol07.it/issue/FSSOE-13
Flarum won’t login the user if the credentials don’t satisfy these rules. It is suggested to enforce these rules (or strictier ones) in your auth system.
If you’re trying to login to Flarum with an user that existed before enabling SSO, you have to use the same Flarum password in your auth system. Otherwise, passwords will mismatch and login fails.
Major changes are marked with
Breaking changes are marked with
Released on October 01, 2022
b923d57 ✨ Added ability to specify the cookie name prefix
f701ef4👷 Added API docs action
fcf2d86👷 Added changelog generator action
d9a76ddDelete issue template
85938c3Don’t allow new issues on Github
f3ed428deps: Support Laravel 9
Released on May 22, 2021
0dd2465🐛 Groups created even if they already exists in Flarum
f3c9c50 🔥 Removed set_groups_admins as no more used
Implementation of this should be made by the user
Released on April 06, 2021
d173cb1 ✨ Addons can now specify what addons are required to be loaded before it
c0dc540 ✨ Allow to change the remember property via the
f152d95 ✨ 💥 New user() method
99c0594 💥 ✨ 🚚 Moved Addons and Cookies features to traits
613b5b5 ✨ Added Remember me checkbox to example + some visual improvements
5865c51 ✨ Changed
Lifetime is deprecated in beta16.
Remember should be set to true when you want to login the user with a “Remember me” option.
edd34eb ✨ Initial attempt to beta16 compatibility
2b2dcb3📝 Updated docs
94a2a84📝 Updated docs
37ce682📝 Updated docs
7b7cbb8📝 PHPDoc fix
6c262d8👽 Nickname attribute instead of display name
443658d 🔥 Removed the getForumLink
URL is accessible via the url property
3f31ea6 ✨ Updated user
7b14a69 🚚 💥 Renamed the
fetchUser method to simply
e9c1c9e 🚚 Moved and Renamed the Basic trait to the Auth trait in the Maicol07\SSO\User\Traits namespace
80d1f7e Minor improvements
c1e71eb addons: 🚚 Renamed master property to flarum (consistency)
e886c59 example: Updated example
204e0a2 examples: ✨ Added users list on the delete page
7f5f752♻️ 🚚 Moved delete and update methods out of the basic trait
e3c00de♻️ Refactor doctum.config.php
a72432d♻️ Refactor doctum.config.php
6331b3c♻️ General refactor
1b6448b💄 Minor example styling improvement
befa080Merge pull request #9 from richstandbrook/patch-1
Requires PHP 7.2+
removeGroups()method. Edit user groups to remove them)
getUsersList()now returns a Laravel collection instead of an array
getUsersList()now supports more than one filter
$set_groups_userto not set groups to an admin user (check API docs)