GRegister

A group-centric invite-based registration system for Matrix-Synapse. Designed with minimal dependencies to allow as much flexibility as possible in front end configurations.

How it works

Invite codes can be generated by group administrators. Each invite code can then be used to register a single account which is automatically added as a member of the group. A little like Slack, but with more flexibility and control over invite distribution.

Note: basic skills in web development are required, and basic PHP will come in handy. GRegister is meant to be integrated into a website, already existing or otherwise. Basic barebones sites work, and, although it may take a little tinkering, it should be usable with many CMS platforms.

Dependencies

• PHP (tested on 7.3), and a web server configured to run it. For example, apache or nginx with php-fpm. You can use the same installation as your Matrix server, but you'll need to make a separate configuration and setup PHP if you haven't already.
  • Make sure the PDO and SQLite drivers are installed and enabled in php.ini: https://www.php.net/manual/en/pdo.installation.php
• An up-and-running Matrix-Synapse homeserver. Tested on 0.99.2-6 (most recent version compatible with older iOS client). If you are using a newer version, please test thoroughly before using it on a live server!
• SQLite. Used by Matrix-Synapse, so it may already be installed.
• Composer, local or global installation: https://getcomposer.org/
  • It is possible to get around using composer. This may be useful to those using shared web hosting with limited capabilities and permissions. To do this, simply include matrix-synapse.php and be careful to ensure your gregister.json is not publically exposed!

Installing

• Configure your web root to be a subdirectory of the GRegister directory. For example, a public folder alongside the src folder included in the repo. Do not set your web root to be the GRegister directory itself!
• Run php composer.phar install from the GRegister directory.
• Create a sqlite database for storing invites created by the system. This can go anywhere as long as permissions are set so it can be written by the web server.
• Edit gregister.json
  • Set "homeserverDomain" to the domain name your home server is using. This is what is entered when setting the server options for logging into the client. No trailing slash!
  • Input into "invitesDatabase" the path to your freshly created invites database.
  • Additionally, for "homeserverDatabase" fill in the location of your Matrix-Synapse homeserver.db database. To find this, check the configuration file you created when installing Matrix-Synapse.
  • Set the amount of time invites last before expiring in "expirationTimeSeconds". The default value 1209600 is 2 weeks.
• Backup your homeserver.db!

Usage

Using composer's autoloader, GRegister can be used from any PHP throughout your site's project. Make sure you have require_once dirname(__DIR__) . '/vendor/autoloader.php'; at the top of any file you intend to use GRegister from.

Start off by creating a GRegistrar instance

// Use gregister.json file in the project directory
$gRegistrar = new GRegister\GRegistrar(); 
// Use gregister.json file located somewhere else
$gRegistrar = new GRegister\GRegistrar( 'path/to/file/.gregister.json' ); 

Make sure to use an error handler to catch and properly format and display messages, such as wrong usernames and passwords or invalid invite codes. Errors are raised as E_USER_WARNING or E_USER_ERROR depending on severity.

Elevating users to group administrators

You will need the username of the user to be elevated, the name of the group, and the username and password of a current admin for authentication.

$gRegistrar.promoteUser( 
    'currentAdminUsername', 
    'currentAdminPassword', 
    'groupName', 
    'usernameToElevate' 
);

Generating invites

You will need the username and password of a current admin of the group for authentication, and the group's name.

$gRegistrar.generateInvite(
    'adminUsername',
    'adminPassword',
    'groupName'
);

Registering a new user

You will need a hashed password for the new user! Matrix synapse uses bcrypt for password hashing - you can find JavaScript implementations to do this client-site. Check out the hash_password script bundled with Matrix-Synapse for more details: https://github.com/matrix-org/synapse/blob/master/scripts/hash_password

$gRegistrar.registerUser(
    'desiredUsername',
    'passwordHash',
    'inviteCode'
);