Matrix Synapse authentication from Unix user accounts

Problem: You have an organization (university, business, hackerspace, etc) with existing user accounts on a Unix server. You want to host Synapse homeserver for them so that they can use their existing accounts to log in. 

Here's how to do it quite easily.

We use three main components:

• Synapse - the Matrix homeserver
• Synapse REST Password provider - This is a plugin to Synapse that acts as a HTTP client asking "I have client with this username and password, is it valid?" 
• pam-auth-rest-api - This is a HTTP server which receives the question, checks Unix PAM (Pluggable Authentication Modules) if the username / password pair is valid, and returns the information to the password provider.

You can run the homeserver on same or different server to where the accounts are. Security-wise it's probably better to have own server for Synapse.

Set up synapse

 

Read the installation instructions. I installed as Debian package. It doesn't matter how you install it. Remember to use postgresql database.

Use federation tester to make sure your homeserver is seen by the federation.

 

Set up REST Password provider

 

Read the instructions here. You just copy the plugin file to a specific directory. In homeserver.yaml you need to add the magic lines:

password_providers:
  - module: "rest_auth_provider.RestAuthProvider"
    config:
      endpoint: "http://server.with.accounts:3000"

 

Set up REST PAM API

This should be done on the computer with the Unix accounts, whether it is the homeserver or not.

Read instructions here.  You'll need to git clone the repository and do some setup. It is a node.js application so you'll need to install required nodejs packages as needed.

There is a systemd service file provided that can be used to automatically start the server.

After you have set up the server, test it with curl by running:

curl -X POST -d '{ "user": { "id": "@john.doe:example.org", "password": "passwordOfTheUser" } }' -H "Content-Type: application/json" http://localhost:3000/_matrix-internal/identity/v1/check_credentials  

This should return json with success: false (or true, if you provide real user credentials). 

You can also do the same test from Synapse server by replacing localhost with the hostname of the account server.

Test the setup

Now you can test the whole pipeline. Open a new private browser tab, load https://riot.im/app , Sign in, change homeserver to your homeserver and enter valid user account credentials. You should be logged in as a new Matrix user on the homeserver.

Note: homeserver name needs to be the real hostname of the server (https://matrix.example.org, not https://example.org).

If something fails, check the Synapse log and systemd log for the REST PAM API.

If you have questions or comment, I'm on #synapse:matrix.org and I'll try to help.


Good luck!

- @cosmo:modeemi.fi

End notes

• The REST Password provider is no longer maintained by its author. I'm tempted to fork and continue work on it unless someone else wants to.
• HTTP request between homeserver and account server is not encrypted. If these are different computers and there is possibility of a MITM attack, It's recommended to encrypt the traffic. I tried stunnel first (failed as the password provider doesn't like self-signed certs) and finally got it working with autossh ssh tunneling. You could also use reverse http proxy, vpn, or anything like that.