cqrenet/mxids
3
0
Fork 0
Code Pull Requests 10 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

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

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

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