From 9a90d846e6f4b974fbefae4bae8c33fc30bf6d58 Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Thu, 14 Sep 2017 04:54:01 +0200 Subject: [PATCH] Improve README - 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) --- README.md | 128 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 82 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 7f26c1da..94ccf115 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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 @@ -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 @@ -81,15 +97,9 @@ 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 @@ -97,10 +107,18 @@ 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" ``` @@ -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 `/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,