Skip to content

Commit

Permalink
Improve README
Browse files Browse the repository at this point in the history 
- List current features
- List features to come
- Improve wording at various places
- Centralise configuration directions
- Improve layout to make it easier for new users (hopefully)
  • Loading branch information
Maxime Dor committed Sep 14, 2017
1 parent 16efe93 commit 9a90d84
Showing 1 changed file with 82 additions and 46 deletions.
128 changes: 82 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,34 @@
mxisd
mxisd - Federated Matrix Identity Server Daemon
-----
![Travis-CI build status](https://travis-ci.org/kamax-io/mxisd.svg?branch=master)

[Overview](#overview) | [Lookup process](#lookup-process) | [Packages](#packages) | [From source](#from-source) | [Network Discovery](#network-discovery) | [Integration](#integration) | [Support](#support)
[Overview](#overview) | [Features](#features) | [Lookup process](#lookup-process) | [Packages](#packages) |
[From source](#from-source) | [Configuration](#configuration) | [Network Discovery](#network-discovery) |
[Integration](#integration) | [Support](#support)

# Overview
mxisd is an implementation of the [Matrix Identity Service specification](https://matrix.org/docs/spec/identity_service/unstable.html)
which provides an alternative to the vector.im and matrix.org Identity servers.
mxisd is a Federated Matrix Identity server aimed to self-hosted Matrix infrastructures.

mxisd is federated and uses a cascading lookup model which performs lookup from a more authoritative to a less authoritative source, usually doing:
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 Identiy Server specifically configured, if part of some sort of group trust
- Root identity store: vector.im/matrix.org central Identity Server
- 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 only aims to support workflow that does NOT break federation or basic lookup process of the Matrix ecosystem.
mxisd provides an alternative to [sydent](https://github.com/matrix-org/sydent), while still connecting to the vector.im and matrix.org Identity servers,
by implementing the [Matrix Identity Service specification](https://matrix.org/docs/spec/identity_service/unstable.html).

**NOTE:** mxisd is **NOT** an authenticator module for homeservers. Identity servers are opaque public directories for those who publish their data on it.
For more details, please read the [Identity Service specification](https://matrix.org/docs/spec/identity_service/unstable.html).
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.
- Support of invitation to rooms by e-mail with e-mail notification to invitee.
- Authentication support in [synapse](https://github.com/matrix-org/synapse) via the [REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth).

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.
Expand All @@ -39,6 +50,27 @@ Given the phone number `+123456789`, the following lookup logic will be performe
See [releases]((https://github.com/kamax-io/mxisd/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](https://github.com/kamax-io/mxisd/releases).

### Configure and run
After installation:
1. Copy the sample config file `/etc/mxisd/mxisd-sample.yaml` to `/etc/mxisd/mxisd.yaml`
2. [Configure](#configuration)
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
Expand All @@ -55,22 +87,6 @@ You can run a container of the given image and test it with the following comman
docker run -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t your-org/mxisd:$(git describe --tags --always --dirty)
```

## Debian
### Download
See the [releases section](https://github.com/kamax-io/mxisd/releases).

### From source
Requirements:
- fakeroot
- dpkg-deb

Run:
```
./gradlew buildDeb
```

You will find the debian package in `build/dist`

# From Source
## Requirements
- JDK 1.8
Expand All @@ -81,26 +97,28 @@ git clone https://github.com/kamax-io/mxisd.git
cd mxisd
./gradlew build
```
then see the [Configuration](#configuration) section.

## Configure
1. Create a new local config: `cp application.example.yaml application.yaml`
2. Set the `server.name` value to the domain value used in your Home Server configuration
3. Set an absolute location for the signing keys using `key.path`
4. Provide the LDAP attributes you want to use for lookup, if you want to use one
5. Edit an entity in your LDAP database and set the configure attribute with a Matrix ID (e.g. `@john.doe:example.org`)

## Test build and configuration
## 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
$ 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",...}
```

Validate your LDAP config and binding info (replace the e-mail):

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"
```
Expand Down Expand Up @@ -137,36 +155,54 @@ chmod a+x /opt/mxisd/mxisd.jar
ln -s /opt/mxisd/mxisd.jar /usr/bin/mxisd
```

2. Copy the config file created earlier `./application.yaml` to `/etc/mxisd/mxisd.yaml`
3. Configure `/etc/mxisd/mxisd.yaml` with production value, `key.path` being the most important - `/var/opt/mxisd/signing.key` is recommended
2. Copy the config file created earlier `./application.example.yaml` to `/etc/mxisd/mxisd.yaml`
3. [Configure](#configuration)
4. Copy `<repo root>/src/systemd/mxisd.service` to `/etc/systemd/system/` and edit if needed
5. Manage service for auto-startup
5. Enable service for auto-startup
```
# Enable service
systemctl enable mxisd
# Start service
```
6. Start mxisd
```
systemctl start mxisd
```

# Configuration
After following the specific instructions to create a config file from the sample:
1. Set the `server.name` value to the domain value used in your Home Server configuration
2. Set an absolute location for the signing keys using `key.path`
3. Set a location for the default SQLite persistence using `storage.provider.sqlite.database`
4. Configure the E-mail invite sender with items starting in `invite.sender.email`

If you want to use the LDAP backend:
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


# Network Discovery
To allow other federated Identity Server to reach yours, configure the following DNS SRV entry (adapt to your values):
```
_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.
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](#integration) for more details.

# Integration
- [HTTPS and Reverse proxy](https://github.com/kamax-io/mxisd/wiki/HTTPS)
- [synapse](https://github.com/kamax-io/mxisd/wiki/Homeserver-Integration)
- [synapse](https://github.com/kamax-io/mxisd/wiki/Homeserver-Integration) as Identity server
- [synapse with REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth/blob/master/README.md)
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](https://matrix.to/#/#mxisd:kamax.io)
For more high-level discussion about the Identity Server architecture/API, go to [#matrix-identity:matrix.org](https://matrix.to/#/#matrix-identity:matrix.org)
If you need help, want to report a bug or just say hi, you can reach us on Matrix at
[#mxisd:kamax.io](https://matrix.to/#/#mxisd:kamax.io) or [directly peek anonymously](https://view.matrix.org/room/!NPRUEisLjcaMtHIzDr:kamax.io/).
For more high-level discussion about the Identity Server architecture/API, go to
[#matrix-identity:matrix.org](https://matrix.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,
Expand Down

0 comments on commit 9a90d84

Please # to comment.