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:
composer update
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 src/Flarum.php
class.
Basically, you need to do this:
use Maicol07\SSO\Flarum;
$flarum = new Flarum($options);
$options
is 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
$username
is a string (the username of the user)
$flarum
is the Flarum object created in the previous step
$flarum_user->attributes->email = 'user@example.com';
$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)
$flarum_user->login();
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 false
ONLY 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: Cryptokeysigner
: Algorithm used to sign the JWT. This can be an object of any of the algorithm classes defined under the Lcobucci\JWT\Signer\Hmac
namespace. Some accepted classes examples:
Lcobucci\JWT\Signer\Hmac\Sha256
(default; fastest on x86 system)Lcobucci\JWT\Signer\Hmac\Sha384
Lcobucci\JWT\Signer\Hmac\Sha512
(stronger, fastest on x64 systems, slower on x86 ones)You can pay with your preferred gateway.
Gateway name | Stripe | PayPal | ||
---|---|---|---|---|
Price | 2,99 € | 2,99 € | ||
Commissions | 5% | 10% | ||
Total Price | 3,15 € | 3,29 € | ||
Payment buttons | Pay with Stripe |
Gateway name | Stripe | PayPal | ||
---|---|---|---|---|
Price | 29,99 € | 29,99 € | ||
Commissions | 5% | 10% | ||
Total Price | 31,49 € | 32,99 € | ||
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-sso
must be installed in Flarummaicol07/flarum_sso_plugin
must be installed in your auth systemCheck 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 actionfcf2d86
👷 Added changelog generator actiond9a76dd
Delete issue template85938c3
Don’t allow new issues on Githubf3ed428
deps: Support Laravel 9Released on May 22, 2021
0dd2465
🐛 Groups created even if they already exists in Flarumf3c9c50
🔥 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 isSessionRemembered
method
f152d95
✨ 💥 New user() method
99c0594
💥 ✨ 🚚 Moved Addons and Cookies features to traits
New methods:
Renamed methods:
Removed methods:
613b5b5
✨ Added Remember me checkbox to example + some visual improvements
5865c51
✨ Changed lifetime
to remember
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
lifetime
setting with remember
getLifeTimeSeconds
method2b2dcb3
📝 Updated docs94a2a84
📝 Updated docs37ce682
📝 Updated docs7b7cbb8
📝 PHPDoc fix6c262d8
👽 Nickname attribute instead of display name443658d
🔥 Removed the getForumLink
URL is accessible via the url property
3f31ea6
✨ Updated user update
method
7b14a69
🚚 💥 Renamed the fetchUser
method to simply fetch
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 traite3c00de
♻️ Refactor doctum.config.phpa72432d
♻️ Refactor doctum.config.php6331b3c
♻️ General refactor768152a
addons: 🚚 setAddonAttributes
renamed to setAddonProperties
1b6448b
💄 Minor example styling improvementbefa080
Merge 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 arraygetUsersList()
now supports more than one filterRemoved setCookie()
function
$set_groups_user
to not set groups to an admin user (check API docs)not_authenticated
error (https://discuss.flarum.org/d/21666-single-sign-on-sso-with-wordpress-integration/157)