From 40705b5d472a64d646b16b6e6d171c42b4848a27 Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Mon, 2 Oct 2017 16:10:22 +0200 Subject: [PATCH] Improved documentation --- README.md | 79 +++++++++++++++++++++----------- docs/README.md | 1 + docs/architecture.md | 43 +++++++++++++++++ docs/features/authentication.md | 25 +++++++++- docs/features/directory-users.md | 2 +- docs/features/federation.md | 24 ++++++++-- 6 files changed, 140 insertions(+), 34 deletions(-) create mode 100644 docs/architecture.md diff --git a/README.md b/README.md index a76c671..38d13e9 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,15 @@ mxisd - Federated Matrix Identity Server Daemon mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures with enhanced features. It is specifically designed to connect to an Identity store (AD/Samba/LDAP, SQL Database, Web services/application, ...) -to ease integration of the Matrix ecosystem with an existing infrastructure, or to build a new one using lasting tools. +and ease the integration of the Matrix ecosystem with an existing infrastructure, or to build a new one using lasting +tools. -mxisd core principle is to map between Matrix IDs and 3PIDs (Thrid-party Identifiers) for the Homeserver and its users. -3PIDs can be anything that identify a user, like: +The core principle of mxisd is to map between Matrix IDs and 3PIDs (Thrid-party Identifiers) for the Homeserver and its +users. 3PIDs can be anything that identify a user, like: +- Full name - Email address - Phone number +- Employee number - Skype/Live ID - Twitter handle - Facebook ID @@ -29,6 +32,9 @@ mxisd core principle is to map between Matrix IDs and 3PIDs (Thrid-party Identif mxisd is an enhanced Identity service, which implements the [Matrix Identity service API](https://matrix.org/docs/spec/identity_service/unstable.html) but also several other features that greatly enhance user experience within Matrix. +mxisd is the one stop shop for anything regarding Authentication, Directory and Identity management in Matrix built as a +single coherent product. + # Features As a [regular Matrix Identity service](docs/features/identity.md): - Search for people by 3PID using its own Identity stores (LDAP, SQL, etc.) @@ -42,17 +48,17 @@ As an enhanced Identity service: - Federated Identity servers, if applicable to the 3PID - Arbitrary Identity servers - Central Matrix Identity servers -- [Extensive control of where 3PIDs are transmited](docs/sessions/3pid.md), so they are not leaked publicly by users +- [Extensive control of where 3PIDs are transmited](docs/sessions/3pid.md), so they are not leaked publicly by users - [Authentication support](docs/features/authentication.md) for [synapse](https://github.com/matrix-org/synapse) via the -[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth). +[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth) - [Directory integration](docs/features/directory-users.md) which allows you to search for users within your -organisation, even without prior Matrix contact. +organisation, even without prior Matrix contact - [Auto-fill of user profile](docs/features/authentication.md) (Display name, 3PIDs) via the [REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth) # Why use mxisd - Use your existing Identity store, do not duplicate information -- Auto-fill user profiles with relevant info +- Auto-fill user profiles with relevant information - As an organisation, stay in control of 3PIDs so they are not published to the central Matrix.org servers where they currently **cannot be removed** - Users can directly find each other using whatever attribute is relevant within your Identity store @@ -83,7 +89,9 @@ You can also use a dedicated domain for mxisd, but will not have access to some Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-io/mxisd/wiki/Gotchas#nating) if you use the same hostname. -The following Quick Start guide assumes you will host the Homeserver and mxisd under the same hostname. +The following Quick Start guide assumes you will host the Homeserver and mxisd under the same hostname. +If you would like a high-level view of the infrastructure and how each feature is integrated, see the +[dedicated document](docs/architecture.md) ## Install Install via: @@ -108,9 +116,10 @@ If your HS/mxisd hostname is not the same as your Matrix domain, configure `serv Complete configuration guide is available [here](docs/configure.md). ## Integrate +For an overview of a typical mxisd infrastructure, see the [dedicated document](docs/architecture.md) ### Reverse proxy #### Apache2 -In the VirtualHost handling the domain with SSL, add the following line, replacing `0.0.0.0` by the right address/host. +In the VirtualHost handling the domain with SSL, add the following line and replace `0.0.0.0` by the right address/host. **This line MUST be present before the one for the homeserver!** ``` ProxyPass /_matrix/identity http://0.0.0.0:8090/_matrix/identity @@ -146,9 +155,10 @@ See the [dedicated document](docs/features/federation.md). ## Validate Log in using your Matrix client and set `https://example.org` as your Identity server URL, replacing `example.org` by the relevant hostname which you configured in your reverse proxy. - -Try to invite `mxisd-lookup-test@kamax.io`, which should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io` +Try to invite `mxisd-lookup-test@kamax.io`, which should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io` + If it worked, it means you are up and running and can enjoy mxisd in its basic mode! Congratulations! +If it did not work, [get in touch](#support) and we'll do our best to get you started. You can now integrate mxisd further with your infrastructure using the various [features](docs/README.md) guides. @@ -170,36 +180,47 @@ First and foremost, the best way to contribute is to use mxisd and tell us about We would love to hear about your experience and get your feedback on how to make it an awesome product. You can contribute as a community member by: -- Opening issues for any weird behaviour or bug. mxisd should feel natural, let us know if it doesn't! +- Opening issues for any weird behaviour or bug. mxisd should feel natural, let us know if it does not! - Helping us improve the documentation: tell us what is good or not good (in an issue or in Matrix), or make a PR with -changes you feel improve the doc -- Contribute code directly: we love contributors! We are quite strict in our reviews but and we'll always review your PR -in a timely fashion. +changes you feel improve the doc. +- Contribute code directly: we love contributors! All your contributions will be licensed under AGPLv3. - Donate! any donation is welcome, regardless how small or big. This will directly be used for the fixed costs and developer time. You can contribute as an organisation/corporation by: -- Get a [support contract](#support-professional). This is the best way you can help us as it ensures mxisd is maintained regularly and you get -direct access to the support team. -- Sponsoring new features or bug fixes. We'll quote the cost of development, at a reduced rate, and maintain the code -in future release of mxisd. (subject to approval of the feature on our end) +- Get a [support contract](#support-professional). This is the best way you can help us as it ensures mxisd is +maintained regularly and you get direct access to the support team. +- Sponsoring new features or bug fixes. [Get in touch](#contact) so we can discuss it further. # FAQ ### Do I need to use mxisd if I run a Homeserver? No, but it is recommended, even if you don't use any backends or integration. mxisd in its default configuration will use federation and involve the central Matrix.org Identity servers when -performing queries, giving you access to at least the same information than if you were not running it. +performing queries, giving you access to at least the same information as if you were not running it. It will also give your users a choice to make their 3PIDs available publicly, ensuring they are made aware of the privacy consequences, which is not the case with the central Matrix.org servers. -So mxisd is like your gatekeeper and guardian angel. It doesn't change what you already know, just adds some nice -simple features on top of it. +So mxisd is like your gatekeeper and guardian angel. It does not change what you already know, just adds some nice +simple features on top of it. + +### I already use the synapse LDAP3 auth provider, why should I care about mxisd? +The [synapse LDAP3 auth provider](https://github.com/matrix-org/matrix-synapse-ldap3) only handles on specific flow: +validate credentials at login. + +It does not: +- Auto-provision user profiles +- Integrate with Identity management +- Integrate with Directory searches +- Protect you against the username case sensitivites issues in synapse + +mxisd is a replacement and enhancement of it, and also offers coherent results in all areas, which LDAP3 auth provider +does not. ### I saw that sydent is the official Identity server implemenation of the Matrix team, I should use that! You can, but [sydent](https://github.com/matrix-org/sydent): -- [was never meant to be self-hosted and should not be done](https://github.com/matrix-org/sydent/issues/22) +- [should not be used and/or self-hosted](https://github.com/matrix-org/sydent/issues/22) - is not meant to be linked to a specific Homeserver / domain - cannot handle federation or proxy lookups, effectively isolating your users from the rest of the network - forces you to duplicate all your identity data, so people can be found by 3PIDs @@ -209,18 +230,18 @@ So really, you should go with mxisd. ### I'm not sure I understand what an "Identity server" is supposed to be or do The current Identity service API is more a placeholder, as the Matrix devs did not have time so far to really work on -what they want to do with that part of the ecosystem. Therefore, "Identity" is a missleading word currently. -Given the scope of the current Identity Service API, their would be best called "Directory and Invitation service". +what they want to do with that part of the ecosystem. Therefore, "Identity" is a misleading word currently. +Given the scope of the current Identity Service API, it would be best called "Invitation service". Because the current scope is so limited and no integration is done with the Homeserver, there was a big lack of features for groups/corporations/organisation. This is where mxisd comes in. -mxisd implements the Identity Service API and also a set of features which are expected by regular users, truely living +mxisd implements the Identity Service API and also a set of features which are expected by regular users, truly living up to its "Identity server" name. ### So mxisd is just a big hack! I don't want to use non-official features! mxisd primary concern is to always be compatible with the Matrix ecosystem and the Identity service API. -Whenever the API will be updated and/or enchanced, mxisd will follow, remaining 100% compatible with the ecosystem. +Whenever the API will be updated and/or enhanced, mxisd will follow, remaining 100% compatible with the ecosystem. We also directly talk with the Matrix developers to ensure all features we implement have their approval, and that we are in line with their vision of Identity management within the Matrix ecosystem. @@ -232,4 +253,6 @@ the door to very nice enhancements and integrations. No # Contact -Get in touch on Matrix: [#mxisd:kamax.io](https://matrix.to/#/#mxisd:kamax.io) +Get in touch via: +- Matrix at [#mxisd:kamax.io](https://matrix.to/#/#mxisd:kamax.io) +- Email, see our website: [Kamax.io](https://www.kamax.io) diff --git a/docs/README.md b/docs/README.md index 4e8b95e..c951e3a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ - [Debian package](install/debian.md) - [Docker](install/docker.md) - [Build from source](build.md) +- [Architecture overview](architecture.md) - [Configuration](configure.md) - Features - [Matrix Identity Service](features/identity.md) diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..7385cce --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,43 @@ +# Architecture +## Overview +### Basic setup without integration or federation +``` + Client + | +TCP 443 + | +---------------------+ +---------------------------+ + +-> | Reverse proxy | | Homeserver | + | | TCP 8008 | | + | /_matrix/* -------------------> | - 3PID invite from client | + | | | | | + | /_matrix/identity/ | | | | + +--|------------------+ +---|-----------------------+ + | | + +<---------------------------------<+ + | Backends + | +-------------------+ +------+ +--------+ + TCP 8090 +-> | mxisd | +-----> | LDAP | -> | SQL DB | + | | | +------+ +--------+ .... + | - Profile's 3PIDs >----+ | + | - 3PID Invites | | | + +-|-----------------+ +>----+ + | | | +--------------------------+ + | | | | Central Identity service | + +>-------------------->+ +-----> | Matrix.org / Vector.im | + | TCP 443 +--------------------------+ + TCP 443 + | +------------------------+ + | | Remote Federated | + | | mxisd servers | + | | | + +--> - 3PID Invites | + +------------------------+ +``` +### With Authentication +See the [dedicated document](features/authentication.md). + +### With Directory +See the [dedicated document](features/directory-users.md). + +### With Federation +See the [dedicated document](features/federation.md). diff --git a/docs/features/authentication.md b/docs/features/authentication.md index d79a030..dbe8aab 100644 --- a/docs/features/authentication.md +++ b/docs/features/authentication.md @@ -1,7 +1,28 @@ # Authentication -Performed via [synapse with REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth/blob/master/README.md) - +Performed via [synapse with REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth/blob/master/README.md) Point the `endpoint` to mxisd internal IP on port 8090 +## Overview +``` + Backends + Client +------+ + | +-------------------------+ +--> | LDAP | + | +---------------+ /_matrix/identity | mxisd | | +------+ + +-> | Reverse proxy | >------------------+ | | | + +--|------------+ | | | | +--------+ + | +-----> Check wiht backends >------+--> | SQL DB | + Login request | | | | +--------+ + | | | | | | + | +--------------------------+ | +-----|-------------------+ +--> Others + +-> | Homeserver | | | + | | | | + | - Validate credentials >----+ | + | Using REST auth module | | + | | | + | - Auto-provision <-------------------<+ + | user profiles | If valid credentials and supported by backend + +--------------------------+ +``` + ## Profile auto-fill To be documented \ No newline at end of file diff --git a/docs/features/directory-users.md b/docs/features/directory-users.md index 0af84d8..e7fecc0 100644 --- a/docs/features/directory-users.md +++ b/docs/features/directory-users.md @@ -46,7 +46,7 @@ Client --> | Reverse proxy ``` Steps: 1. The intercepted request is directly sent to mxisd instead of the Homeserver. -2. Enabled backends are queried for any math on the search value sent by the client. +2. Enabled backends are queried for any match on the search value sent by the client. 3. The Homeserver, from which the request was intercepted, is queried using the same request as the client. Its address is resolved using the DNS Overwrite feature to reach its internal address on a non-encrypted port. 4. Results from backends and the Homeserver are merged together and sent back to the client, believing it was the HS diff --git a/docs/features/federation.md b/docs/features/federation.md index 71319bd..446b2d5 100644 --- a/docs/features/federation.md +++ b/docs/features/federation.md @@ -1,8 +1,27 @@ # Identity service Federation +## Overview +``` + +-------------------+ +-------------> +----------+ + | mxisd | | | Backends | + | | | +------> +----------+ + | | | | + | Invites / Lookups | | | + Federated | +--------+ | | | +-------------------+ + Identity ---->| Remote |>-----------+ +------> | Remote Federated | + Server | +--------+ | | | mxisd servers | + | | | +-------------------+ + | +--------+ | | + Homeserver --->| Local |>------------------+ + and clients | +--------+ | | +--------------------------+ + +-------------------+ +------> | Central Identity service | + | Matrix.org / Vector.im | + +--------------------------+ +``` 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 - + +## Configuration 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!** ``` @@ -11,5 +30,4 @@ _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, TCP port `8090` of mxisd should be behind a reverse proxy which does HTTPS. -See the [main README integration section](../README.md#integration) for more details. +The port must be HTTPS capable which is what you get in a regular setup with a reverse proxy from 443 to TCP 8090 of mxisd.