mxids/README.md

mxisd - Federated Matrix Identity Server Daemon

Overview | Features | Lookup process | Packages | From source | Configuration | Network Discovery | Integration | Support

Overview

mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures.

mxisd uses a cascading lookup model which performs lookup from a more authoritative to a less authoritative source, usually doing:

• Local identity stores: LDAP, etc.
• Federated identity stores: another Identity Server in charge of a specific domain, if applicable
• Configured identity stores: another Identity Server specifically configured, if part of some sort of group trust
• Root identity store: vector.im/matrix.org central Identity Servers

mxisd provides an alternative to sydent, while still connecting to the vector.im and matrix.org Identity servers, by implementing the Matrix Identity Service specification.

mxisd only aims to support workflows that do NOT break federation or basic lookup processes of the Matrix ecosystem.

Features

• Single lookup of 3PID (E-mail, phone number, etc.) by the Matrix Client or Homeserver.
• Bulk lookups when trying to find possible matches within contacts in Android and iOS clients.
• Bind of 3PID by a Matrix user within a Matrix client - See documentation
• Support of invitation to rooms by e-mail with e-mail notification to invitee.
• Authentication support in synapse via the REST auth module.

In the pipe:

• Support to proxy 3PID bindings in user profile to the central Matrix.org servers

Lookup Process

Default Lookup strategy will use a priority order and a configurable recursive/local type of request.

E-mail

Given the 3PID john.doe@example.org, the following will be performed until a mapping is found:

• LDAP: lookup the Matrix ID (partial or complete) from a configurable attribute using a dedicated query.
• DNS: lookup another Identity Server using the domain part of an e-mail and:
  • Look for a SRV record under _matrix-identity._tcp.example.org
  • Lookup using the base domain name example.org
• Forwarder: Proxy the request to other configurable identity servers.

Phone number

Given the phone number +123456789, the following lookup logic will be performed:

• LDAP: lookup the Matrix ID (partial or complete) from a configurable attribute using a dedicated query.
• Forwarder: Proxy the request to other configurable identity servers.

Packages

See releases for native installers of supported systems.
If none is available, please use other packages or build from source.

Debian

Download

See the releases section.

Configure and run

After installation:

1. Copy the sample config file /etc/mxisd/mxisd-sample.yaml to /etc/mxisd/mxisd.yaml
2. Configure
3. Start the service: sudo systemctl start mxisd

From source

Requirements:

• fakeroot
• dpkg-deb

Run:

./gradlew buildDeb 

You will find the debian package in build/dist

Docker

docker pull kamax/mxisd

For more info, see the public repository

From source

Build mxisd then build the docker image:

./gradlew dockerBuild

You can run a container of the given image and test it with the following command (adapt volumes host paths):

docker run -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t kamax/mxisd:latest-dev

From Source

Requirements

• JDK 1.8

Build

git clone https://github.com/kamax-io/mxisd.git
cd mxisd
./gradlew build

then see the Configuration section.

Test build

Start the server in foreground to validate the build:

java -jar build/libs/mxisd.jar

Ensure the signing key is available:

$ curl http://localhost:8090/_matrix/identity/api/v1/pubkey/ed25519:0
{"public_key":"..."}

Test basic recursive lookup (requires Internet connection with access to TCP 443):

$ curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=mxisd-lookup-test@kamax.io'
{"address":"mxisd-lookup-test@kamax.io","medium":"email","mxid":"@mxisd-lookup-test:kamax.io",...}

If you enabled LDAP, you can also validate your config with a similar request after replacing the address value with something present within your LDAP

curl "http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=john.doe@example.org"

If you plan on testing the integration with a homeserver, you will need to run an HTTPS reverse proxy in front of it as the reference Home Server implementation synapse requires a HTTPS connection to an ID server.
See the Integration section for more details.

Install

After building the software, run all the following commands as root or using sudo

1. Prepare files and directories:

# Create a dedicated user
useradd -r mxisd

# Create bin directory
mkdir /opt/mxisd

# Create config directory and set ownership
mkdir /etc/mxisd
chown mxisd /etc/mxisd

# Create data directory and set ownership
mkdir /var/opt/mxisd
chown mxisd /var/opt/mxisd

# Copy <repo root>/build/libs/mxisd.jar to bin directory
cp ./build/libs/mxisd.jar /opt/mxisd/
chown mxisd /opt/mxisd/mxisd.jar
chmod a+x /opt/mxisd/mxisd.jar

# Create symlink for easy exec
ln -s /opt/mxisd/mxisd.jar /usr/bin/mxisd

2. Copy the config file created earlier ./application.example.yaml to /etc/mxisd/mxisd.yaml
3. Configure
4. Copy <repo root>/src/systemd/mxisd.service to /etc/systemd/system/ and edit if needed
5. Enable service for auto-startup

systemctl enable mxisd

6. Start mxisd

systemctl start mxisd

Configuration

After following the specific instructions to create a config file from the sample:

1. Set the matrix.domain value to the domain value used in your Home Server configuration
2. Set an absolute location for the signing keys using key.path
3. Configure the E-mail notification sender with items starting with:

• threepid.medium.email.identity
• threepid.medium.email.connectors.smtp

4. If you would like to support Phone number validation, see the Twilio configuration

In case your IS public domain does not match your Matrix domain, see server.name and server.publicUrl config items.

Backends

LDAP (AD, Samba, LDAP)

If you want to use LDAP backend as an Identity store:

1. Enable it with ldap.enabled
2. Configure connection options using items starting in ldap.connection
3. You may want to valid default values for ldap.attribute items

SQL (SQLite, PostgreSQL)

If you want to connect to use a synapse DB (SQLite or PostgreSQL) as Identity store, follow the example config for sql config items.

REST (Webapps/websites integration)

If you want to use the REST backend as an Identity store:

1. Enable it with rest.enabled
2. Configure options starting with rest and see the dedicated documentation in docs/backends/rest.md

Network Discovery

To allow other federated Identity Server to reach yours, the same algorithm used for Homeservers takes place:

1. Check for the appropriate DNS SRV record
2. If not found, use the base domain

If your Identity Server public hostname does not match your Matrix domain, configure the following DNS SRV entry and replace matrix.example.com by your Identity server public hostname - Make sure to end with a final dot!

_matrix-identity._tcp.example.com. 3600 IN SRV 10 0 443 matrix.example.com.

This would only apply for 3PID that are DNS-based, like e-mails. For anything else, like phone numbers, no federation is currently possible.

The port must be HTTPS capable. Typically, the port 8090 of mxisd should be behind a reverse proxy which does HTTPS. See the integration section for more details.

Integration

• HTTPS and Reverse proxy
• synapse as Identity server
• synapse with REST auth module as authentication module

Support

Community

If you need help, want to report a bug or just say hi, you can reach us on Matrix at #mxisd:kamax.io or directly peek anonymously. For more high-level discussion about the Identity Server architecture/API, go to #matrix-identity:matrix.org

Professional

If you would prefer professional support/custom development for mxisd and/or for Matrix in general, including other open source technologies/products, please visit our website to get in touch with us and get a quote.