tomas.kracmar/ma1sd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki 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 `/`.

29
docs/features/bridge-integration.md
View File

@@ -1 +1,28 @@
To be documented
# Bridge Integration
To help natural bridge integration into the regular usage of a Matrix client, mxisd provides a way for bridge to reply
to 3PID queries if no mapping was found, allowing seamless bridging to a network.
This is performed by implementing a specific endpoint on the bridge to map a 3PID lookup to a virtual user.
**NOTE**: This document is incomplete and might be misleading. In doubt, come in our Matrix room.
You can also look at our [Email Bridge README](https://github.com/kamax-io/matrix-appservice-email#mxisd) for an example
of working configuration.
## Configuration
```yaml
lookup.recursive.bridge.enabled: <boolean>
lookup.recursive.bridge.recursiveOnly: <boolean>
lookup.recursive.bridge.server: <URL to the bridge endpoint for all 3PID medium>
lookup.recursive.bridge.mappings:
<3PID MEDIUM HERE>: <URL to dedicated bridge for that medium>
```
## Integration
Implement a simplified version of the [Identity service single lookup endpoint](https://kamax.io/matrix/api/identity_service/unstable.html#get-matrix-identity-api-v1-lookup)
with only the following parameters needed:
- `address`
- `medium`
- `mxid`
Or an empty object if no resolution exists or desired.

127
docs/features/directory-users.md → docs/features/directory.md
View File

@@ -7,10 +7,6 @@
- [Apache2](#apache2)
- [nginx](#nginx)
- [DNS Overwrite](#dns-overwrite)
- [Backends](#backends)
- [LDAP](#ldap)
- [SQL](#sql)
- [REST](#rest)
- [Next steps](#next-steps)
## Description
@@ -18,17 +14,17 @@ This feature allows you to search for existing and/or potential users that are a
or that already share a room with you on the Homeserver.
Without any integration, synapse:
- Only search within the users **already** known to you
- Only search within the users **already** known to you or in public rooms
- Only search on the Display Name and the Matrix ID
With mxisd integration, you can:
By enabling this feature, you can by default:
- Search on Matrix ID, Display name and 3PIDs (Email, phone numbers) of any users already in your configured backend
- Search for users which you are not in contact with yet. Super useful for corporations who want to give Matrix access
internally, so users can just find themselves **prior** to having any common room(s)
- Use any attribute of your backend to extend the search!
- Include your homeserver search results to those found by mxisd (default behaviour, no configuration required)
- Add extra attributes of your backend to extend the search
- Include your homeserver search results to those found by mxisd
By integrating mxisd, you get the default behaviour with all the extras, ensuring your users will always find each other.
By integrating mxisd, you get the default behaviour and a bunch of extras, ensuring your users will always find each other.
## Overview
This is performed by intercepting the Homeserver endpoint `/_matrix/client/r0/user_directory/search` like so:
@@ -49,31 +45,28 @@ Client --> | Reverse proxy
```
Steps:
1. The intercepted request is directly sent to mxisd instead of the Homeserver.
2. Enabled backends are queried for any match on the search value sent by the client.
2. Identity stores 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
Its address is resolved using the DNS Overwrite feature to reach its internal address on a non-encrypted port.
4. Results from Identity stores and the Homeserver are merged together and sent back to the client, believing it was the HS
which directly answered the request.
## Requirements
- Reverse proxy setup, which you should already have in place if you use mxisd
- Compatible backends:
- LDAP
- SQL
- REST
- At least one compatible [Identity store](../stores/README.md) enabled
## Configuration
### Reverse Proxy
#### Apache2
The specific configuration to put under the relevant `VirtualHost`:
```
```apache
ProxyPass /_matrix/client/r0/user_directory/ http://0.0.0.0:8090/_matrix/client/r0/user_directory/
```
`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:
```
```apache
<VirtualHost *:443>
ServerName example.org
@@ -81,14 +74,14 @@ Your `VirtualHost` should now look like this:
ProxyPreserveHost on
ProxyPass /_matrix/client/r0/user_directory/ http://localhost:8090/_matrix/client/r0/user_directory/
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>
```
#### nginx
The specific configuration to add under your `server` section is:
```
```nginx
location /_matrix/client/r0/user_directory {
proxy_pass http://0.0.0.0:8090/_matrix/client/r0/user_directory;
proxy_set_header Host $host;
@@ -97,7 +90,7 @@ location /_matrix/client/r0/user_directory {
```
Your `server` section should now look like this:
```
```nginx
server {
listen 443 ssl;
server_name example.org;
@@ -129,7 +122,7 @@ Just like you need to configure a reverse proxy to send client requests to mxisd
the internal IP of the Homeserver so it can talk to it directly to integrate its directory search.
To do so, use the following configuration:
```
```yaml
dns.overwrite.homeserver.client:
- name: 'example.org'
value: 'http://localhost:8008'
@@ -138,94 +131,12 @@ dns.overwrite.homeserver.client:
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 intenral URL of the Homeserver, without any `/_matrix/..` or trailing `/`.
### Backends
#### LDAP
To ensure Directory feature works, here's how the LDAP configuration should look like:
```
ldap:
enabled: false
filter: '(memberOf=CN=Matrix Users,OU=Groups,DC=example,DC=org)'
connection:
host: 'ldapIpOrDomain'
bindDn: 'CN=Matrix Identity Server,OU=Accounts,DC=example,DC=org'
bindPassword: 'mxisd'
baseDn: 'OU=Accounts,DC=example,DC=org'
attribute:
uid:
type: 'uid'
value: 'userPrincipalName'
name: 'displayName'
threepid:
email:
- 'mailPrimaryAddress'
- 'mail'
- 'otherMailbox'
msisdn:
- 'telephoneNumber'
- 'mobile'
- 'homePhone'
- 'otherTelephone'
- 'otherMobile'
- 'otherHomePhone'
directory:
attribute:
other:
- 'employeeNumber'
- 'someOtherAttribute'
```
Only include the `attribute` sub-sections if you would like to set another value. Else, it is best not to include them
to inherit the default values.
If you would like to include an attribute which is not a display name or a 3PID, you can use the
`directory.attribute.other` to list any extra attributes you want included in searches. If you do not want to include
any extra attribute, that configuration section can be skipped.
#### SQL
If you plan to integrate directory search directly with synapse, use the `synapseSql` provider, based on the following
config:
```
synapseSql:
enabled: true
type: <database ID>
connection: '<connection info>'
```
`type` and `connection`, including any other configuration item, follow the same values as the regular [SQL backend](../backends/sql.md).
---
For the regular SQL backend, the following configuration items are available:
```
sql:
directory:
enabled: true
query:
name:
type: 'localpart'
value: 'SELECT idColumn, displayNameColumn FROM table WHERE displayNameColumn LIKE ?'
threepid:
type: 'localpart'
value: 'SELECT idColumn, displayNameColumn FROM table WHERE threepidColumn LIKE ?'
```
For each query, `type` can be used to tell mxisd how to process the ID column:
- `localpart` will append the `matrix.domain` to it
- `mxid` will use the ID as-is. If it is not a valid Matrix ID, the search will fail.
`value` is the SQL query and must return two columns:
- The first being the User ID
- The second being its display name
#### REST
See the [dedicated document](../backends/rest.md)
#### Wordpress
See the [dedicated document](../backends/wordpress.md)
`value` is the base internal URL of the Homeserver, without any `/_matrix/..` or trailing `/`.
## Next steps
### Homeserver results
You can configure if the Homeserver should be queried at all when doing a directory search.
To disable Homeserver results, set the following in mxisd config file:
```
To disable Homeserver results, set the following in mxisd configuration file:
```yaml
directory.exclude.homeserever: true
```

36
docs/features/federation.md
View File

@@ -1,4 +1,15 @@
# Identity service Federation
# Federation
Federation is the process by which domain owners can make compatible 3PIDs mapping auto-discoverable by looking for another
Federated Identity server using the DNS domain part of the 3PID.
Emails are the best candidate for this kind of resolution which are DNS domain based already.
On the other hand, Phone numbers cannot be resolved this way.
For 3PIDs which are not compatible with the DNS system, mxisd will talk to the central Identity server of matrix.org by
default.
Outbound federation is enabled by default while inbound federation is opt-in and require a specific DNS record.
## Overview
```
+-------------------+ +-------------> +----------+
@@ -17,17 +28,24 @@
| 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!**
## Inbound
If you would like to be reachable for lookups over federation, create the following DNS SRV entry and replace
`matrix.example.com` by your Identity server public hostname:
```
_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 which is what you get in a regular setup with a reverse proxy from 443 to TCP 8090 of mxisd.
## Outbound
If you would like to disable outbound federation and isolate your identity server from the rest of the Matrix network,
use the following mxisd configuration options:
```yaml
lookup.recursive.enabled: false
invite.resolution.recursive: false
session.policy.validation.forLocal.toRemote.enabled: false
session.policy.validation.forRemote.toRemote.enabled: false
```
There is currently no way to selectively disable federation towards specific servers, but this feature is planned.

7
docs/features/identity.md
View File

@@ -1,9 +1,9 @@
# Matrix Identity Service
# Identity
**WARNING**: This document is incomplete and can be missleading.
Implementation of the [Unofficial Matrix Identity Service API](https://kamax.io/matrix/api/identity_service/unstable.html).
## Invitation
## Room Invitations
Resolution can be customized using the following configuration:
`invite.resolution.recursive`
@@ -16,3 +16,6 @@ Resolution can be customized using the following configuration:
`invite.resolution.timer`
- Default value: `1`
- Description: How often, in minutes, mxisd should try to resolve pending invites.
## 3PID addition to user profile
See the [3PID session documents](../threepids/session)

7
docs/features/profile.md
View File

@@ -1,12 +1,9 @@
# Profile enhancement
**WARNING**: Alpha feature not officially supported. Do not use.
## Configuration
### Reverse proxy
#### Apache
```
```apache
ProxyPassMatch "^/_matrix/client/r0/profile/([^/]+)$" "http://127.0.0.1:8090/_matrix/client/r0/profile/$1"
ProxyPassMatch "^/_matrix/client/r0/profile/([^/]+)/(.+)" "http://127.0.0.1:8008/_matrix/client/r0/profile/$1/$2"
```