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

Documentation enhancements (#73)

Browse Source
This commit is contained in:
Max Dor
2018-04-13 03:26:33 +02:00
committed by GitHub
parent 1e413af019
commit ef80f4aa30
36 changed files with 970 additions and 1016 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/features/authentication.md
View File

@@ -1,60 +1,59 @@
# Authentication
- [Description](#description)
- [Overview](#overview)
- [Getting started](#getting-started)
- [Synapse](#synapse)
- [Basic](#basic)
- [Overview](#overview)
- [synapse](#synapse)
- [mxisd](#mxisd)
- [Validate](#validate)
- [Next steps](#next-steps)
- [Profile auto-fil](#profile-auto-fill)
- [Advanced Authentication](#advanced-authentication)
- [Next steps](#next-steps)
- [Profile auto-fil](#profile-auto-fill)
- [Advanced](#advanced)
- [Overview](#overview-1)
- [Requirements](#requirements)
- [Configuration](#configuration)
- [Reverse Proxy](#reverse-proxy)
- [Apache2](#apache2)
- [DNS Overwrite](#dns-overwrite)
- [Backends](#backends)
## Description
Authentication is an enhanced Identity feature of mxisd to ensure coherent and centralized identity management.
Authentication is an enhanced feature of mxisd to ensure coherent and centralized identity management.
It allows to use Identity stores configured in mxisd to authenticate users on your Homeserver.
This feature can also provide the ability to users to login on the Homeserver using their third party identities (3PIDs) provided by an Identity store.
Authentication is divided into two parts:
- [Basic](#basic): authenticate with a regular username.
- [Advanced](#advanced): same as basic with extra ability to authenticate using a 3PID.
## Overview
An overview of the Authentication process is depicted below:
## Basic
Authentication by username is possible by linking synapse and mxisd together using a specific module for synapse, also
known as password provider.
### Overview
An overview of the Basic Authentication process:
```
Backends
Identity stores
Client +------+
| +-------------------------+ +--> | LDAP |
| +---------------+ /_matrix/identity | mxisd | | +------+
+-> | Reverse proxy | >------------------+ | | |
+--|------------+ | | | | +--------+
| +-----> Check with backends >------+--> | SQL DB |
| +-----> Check ID stores >------+--> | SQL DB |
Login request | | | | +--------+
| | | | | |
| +--------------------------+ | +-----|-------------------+ +--> Others
| +--------------------------+ | +-----|-------------------+ +--> ...
+-> | Homeserver | | |
| | | |
| - Validate credentials >----+ |
| Using REST auth module | |
| | |
| - Auto-provision <-------------------<+
| user profiles | If valid credentials and supported by backend
| user profiles | If valid credentials and supported by Identity store(s)
+--------------------------+
```
Performed on [synapse with REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth/blob/master/README.md)
## Getting started
Authentication is possible by linking synapse and mxisd together using the REST auth module
(also known as password provider).
### Synapse
- Install the [REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth).
- Edit your synapse configuration:
- Install the [password provider](https://github.com/kamax-io/matrix-synapse-rest-auth)
- Edit your **synapse** configuration:
- As described by the auth module documentation
- Set `endpoint` to `http://mxisdAddress:8090` - Replace `mxisdAddress` by an IP/host name that provides a direct
connection to mxisd.
@@ -62,25 +61,23 @@ Authentication is possible by linking synapse and mxisd together using the REST
- Restart synapse
### mxisd
- Configure and enable at least one [Identity store](../backends/)
- Configure and enable at least one [Identity store](../stores/README.md)
- Restart mxisd
### Validate
Login on the Homeserver using credentials present in your backend.
Login on the Homeserver using credentials present in one of your Identity stores.
## Next steps
### Profile auto-fill
Auto-filling user profile depends on two conditions:
- The REST auth module is configured for it, which is the case by default
- Your Identity store is configured to provide profile data. See your Identity store [documentation](../backends/) on
how to enable the feature.
Auto-filling user profile depends on its support by your configured Identity stores.
See your Identity store [documentation](../stores/README.md) on how to enable the feature.
## Advanced Authentication
The Authentication feature allows users to login to their Homeserver by using their 3PIDs registered in an available Identity store.
## Advanced
The Authentication feature allows users to login to their Homeserver by using their 3PIDs in a configured Identity store.
### Overview
This is performed by intercepting the Homeserver endpoint `/_matrix/client/r0/login` as depicted below:
```
+----------------------------+
| Reverse Proxy |
@@ -106,31 +103,28 @@ Client+---->| /_matrix/client/r0/login +---------------->|
Steps of user authentication using a 3PID:
1. The intercepted login request is directly sent to mxisd instead of the Homeserver.
2. Enabled backends are queried for a matching user identity in order to modify the request to use the user name.
3. The Homeserver, from which the request was intercepted, is queried using the request at previous step. Its address is resolved using the DNS Overwrite feature to reach its internal address on a non-encrypted port.
2. Identity stores are queried for a matching user identity in order to modify the request to use the user name.
3. The Homeserver, from which the request was intercepted, is queried using the request at previous step.
Its address is resolved using the DNS Overwrite feature to reach its internal address on a non-encrypted port.
4. The response from the Homeserver is sent back to the client, believing it was the HS which directly answered.
### Requirements
- [Basic Authentication configured and working](#basic)
- Reverse proxy setup
- Homeserver
- Compatible Identity backends:
- LDAP
- REST
- Wordpress
- Compatible [Identity store](../stores/README.md)
### Configuration
#### Reverse Proxy
##### Apache2
The specific configuration to put under the relevant `VirtualHost`:
```
```apache
ProxyPass /_matrix/client/r0/login http://localhost:8090/_matrix/client/r0/login
```
`ProxyPreserveHost` or equivalent must be enabled to detect to which Homeserver mxisd should talk to when building results.
`ProxyPreserveHost` or equivalent **must** be enabled to detect to which Homeserver mxisd should talk to when building results.
Your VirtualHost should now look like this:
```
Your VirtualHost should now look similar to:
```apache
<VirtualHost *:443>
ServerName example.org
@@ -138,25 +132,23 @@ Your VirtualHost should now look like this:
ProxyPreserveHost on
ProxyPass /_matrix/client/r0/login http://localhost:8090/_matrix/client/r0/login
ProxyPass /_matrix/identity/ http://localhost:8090/_matrix/identity/
ProxyPass /_matrix/ http://localhost:8008/_matrix/
ProxyPass /_matrix/identity http://localhost:8090/_matrix/identity
ProxyPass /_matrix http://localhost:8008/_matrix
</VirtualHost>
```
#### DNS Overwrite
Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with the internal IP of the Homeserver so it can talk to it directly to integrate its directory search.
Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with
the internal IP of the Homeserver so it can talk to it directly to integrate its directory search.
To do so, put the following configuration in your `application.yaml`:
```
To do so, put the following configuration in your mxisd configuration:
```yaml
dns.overwrite.homeserver.client:
- name: 'example.org'
value: 'http://localhost:8008'
```
`name` must be the hostname of the URL that clients use when connecting to the Homeserver.
In case the hostname is the same as your Matrix domain, you can use `${matrix.domain}` to auto-populate the `value` using the `matrix.domain` configuration option and avoid duplicating it.
In case the hostname is the same as your Matrix domain, you can use `${matrix.domain}` to auto-populate the `value`
using the `matrix.domain` configuration option and avoid duplicating it.
value is the base internal URL of the Homeserver, without any /_matrix/.. or trailing /.
#### Backends
The Backends should be configured as described in the documentation of the [Directory User](directory-users.md) feature.
`value` is the base internal URL of the Homeserver, without any `/_matrix/..` or trailing `/`.