cqrenet/mxids
3
0
Fork 0
Code Pull Requests 4 Actions Releases Activity

Improved documentation

Browse Source
This commit is contained in:
Maxime Dor
2017-10-02 16:10:22 +02:00
parent 642d560ba9
commit 40705b5d47
6 changed files with 140 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
README.md
View File

@@ -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.)
@@ -44,15 +50,15 @@ As an enhanced Identity service:
- Central Matrix Identity servers
- [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
@@ -84,6 +90,8 @@ Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-io/mxisd/wiki/
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`
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
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)

1
docs/README.md
View File

@@ -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)

43
docs/architecture.md Normal file
View File

@@ -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).

23
docs/features/authentication.md
View File

@@ -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)
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

2
docs/features/directory-users.md
View File

@@ -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

22
docs/features/federation.md
View File

@@ -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.