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

Rename config file, parameters, application name, package.

Browse Source
This commit is contained in:
Anatoly Sablin
2019-07-11 22:26:20 +03:00
parent c3262a9f25
commit e6fec9199d
41 changed files with 263 additions and 263 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/features/authentication.md
View File

@@ -3,7 +3,7 @@
- [Basic](#basic)
- [Overview](#overview)
- [synapse](#synapse)
- [mxisd](#mxisd)
- [ma1sd](#ma1sd)
- [Validate](#validate)
- [Next steps](#next-steps)
- [Profile auto-fil](#profile-auto-fill)
@@ -16,15 +16,15 @@
- [DNS Overwrite](#dns-overwrite)
## Description
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.
Authentication is an enhanced feature of ma1sd to ensure coherent and centralized identity management.
It allows to use Identity stores configured in ma1sd to authenticate users on your Homeserver.
Authentication is divided into two parts:
- [Basic](#basic): authenticate with a regular username.
- [Advanced](#advanced): same as basic with extra abilities like authenticate using a 3PID or do username rewrite.
## Basic
Authentication by username is possible by linking synapse and mxisd together using a specific module for synapse, also
Authentication by username is possible by linking synapse and ma1sd together using a specific module for synapse, also
known as password provider.
### Overview
@@ -33,7 +33,7 @@ An overview of the Basic Authentication process:
Identity stores
Client +------+
| +-------------------------+ +--> | LDAP |
| +---------------+ /_matrix/identity | mxisd | | +------+
| +---------------+ /_matrix/identity | ma1sd | | +------+
+-> | Reverse proxy | >------------------+ | | |
+--|------------+ | | | | +--------+
| +-----> Check ID stores >------+--> | SQL DB |
@@ -55,14 +55,14 @@ Performed on [synapse with REST auth module](https://github.com/kamax-io/matrix-
- 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.
- Set `endpoint` to `http://ma1sdAddress:8090` - Replace `ma1sdAddress` by an IP/host name that provides a direct
connection to ma1sd.
This **MUST NOT** be a public address, and SHOULD NOT go through a reverse proxy.
- Restart synapse
### mxisd
### ma1sd
- Configure and enable at least one [Identity store](../stores/README.md)
- Restart mxisd
- Restart ma1sd
### Validate
Login on the Homeserver using credentials present in one of your Identity stores.
@@ -93,7 +93,7 @@ This is performed by intercepting the Homeserver endpoint `/_matrix/client/r0/lo
| | Step 1 +---------------------------+ Step 2
| | | |
Client+---->| /_matrix/client/r0/login +---------------->| | Look up address +---------+
| ^ | | mxisd - Identity server +----------------->| Backend |
| ^ | | ma1sd - Identity server +----------------->| Backend |
| | | | | +---------+
| /_matrix/* +--+ +---------------------+ |
| | | +---------------+-----------+
@@ -110,7 +110,7 @@ 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.
1. The intercepted login request is directly sent to ma1sd instead of the Homeserver.
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.
@@ -129,7 +129,7 @@ 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 ma1sd should talk to when building results.
Your VirtualHost should now look similar to:
```apache
@@ -188,10 +188,10 @@ server {
#### DNS Overwrite
Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with
Just like you need to configure a reverse proxy to send client requests to ma1sd, you also need to configure ma1sd 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 mxisd configuration:
To do so, put the following configuration in your ma1sd configuration:
```yaml
dns:
overwrite:
@@ -214,7 +214,7 @@ The following features are available after you have a working Advanced setup:
- Username rewrite: Allows you to rewrite the username of a regular login/pass authentication to a 3PID, that then gets resolved using the regular lookup process. Most common use case is to allow login with numerical usernames on synapse, which is not possible out of the box.
#### Username rewrite
In mxisd config:
In ma1sd config:
```yaml
auth:
rewrite:

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

@@ -1,11 +1,11 @@
# Bridge Integration
To help natural bridge integration into the regular usage of a Matrix client, mxisd provides a way for bridge to reply
To help natural bridge integration into the regular usage of a Matrix client, ma1sd 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-matrix/matrix-appservice-email#mxisd) for an example
You can also look at our [Email Bridge README](https://github.com/kamax-matrix/matrix-appservice-email#ma1sd) for an example
of working configuration.
## Configuration

16
docs/features/directory.md
View File

@@ -22,9 +22,9 @@ By enabling this feature, you can by default:
- 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)
- Add extra attributes of your backend to extend the search
- Include your homeserver search results to those found by mxisd
- Include your homeserver search results to those found by ma1sd
By integrating mxisd, you get the default behaviour and a bunch of extras, ensuring your users will always find each other.
By integrating ma1sd, 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:
@@ -33,7 +33,7 @@ This is performed by intercepting the Homeserver endpoint `/_matrix/client/r0/us
Client --> | Reverse proxy Step 2
| Step 1 +-------------------------+
| /_matrix/client/r0/user_directory/search ----------> | | Search in +---------+
| /\ | mxisd - Identity server | -----------> | Backend |
| /\ | ma1sd - Identity server | -----------> | Backend |
| /_matrix/* \----------------------------- | | all users +---------+
| | Step 4: Send back merged results +-------------------------+
+ | |
@@ -44,7 +44,7 @@ Client --> | Reverse proxy
+------------+ /_matrix/client/r0/user_directory/search
```
Steps:
1. The intercepted request is directly sent to mxisd instead of the Homeserver.
1. The intercepted request is directly sent to ma1sd instead of the Homeserver.
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.
@@ -52,7 +52,7 @@ Steps:
which directly answered the request.
## Requirements
- Reverse proxy setup, which you should already have in place if you use mxisd
- Reverse proxy setup, which you should already have in place if you use ma1sd
- At least one compatible [Identity store](../stores/README.md) enabled
## Configuration
@@ -62,7 +62,7 @@ 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
`ProxyPreserveHost` or equivalent must be enabled to detect to which Homeserver ma1sd should talk to when building
results.
Your `VirtualHost` should now look like this:
@@ -118,7 +118,7 @@ server {
```
### DNS Overwrite
Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with
Just like you need to configure a reverse proxy to send client requests to ma1sd, you also need to configure ma1sd with
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:
@@ -136,7 +136,7 @@ dns:
## 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 configuration file:
To disable Homeserver results, set the following in ma1sd configuration file:
```yaml
directory:
exclude:

22
docs/features/experimental/application-service.md
View File

@@ -11,7 +11,7 @@ The following capabilities are provided in this feature:
> **NOTE:** Make sure you are familiar with [configuration format and rules](../../configure.md).
Integration as an Application service is a three steps process:
1. Create the baseline mxisd configuration to allow integration.
1. Create the baseline ma1sd configuration to allow integration.
2. Integrate with the homeserver.
3. Configure the specific capabilities, if applicable.
@@ -22,11 +22,11 @@ Under the `appsvc` namespace:
| Key | Type | Required | Default | Purpose |
|-----------------------|---------|----------|---------|----------------------------------------------------------------|
| `enabled` | boolean | No | `false` | Globally enable/disable the feature |
| `user.main` | string | No | `mxisd` | Localpart for the main appservice user |
| `user.main` | string | No | `ma1sd` | Localpart for the main appservice user |
| `endpoint.toHS.url` | string | Yes | *None* | Base URL to the Homeserver |
| `endpoint.toHS.token` | string | Yes | *None* | Token to use when sending requests to the Homeserver |
| `endpoint.toAS.url` | string | Yes | *None* | Base URL to mxisd from the Homeserver |
| `endpoint.toAS.token` | string | Yes | *None* | Token for the Homeserver to use when sending requests to mxisd |
| `endpoint.toAS.url` | string | Yes | *None* | Base URL to ma1sd from the Homeserver |
| `endpoint.toAS.token` | string | Yes | *None* | Token for the Homeserver to use when sending requests to ma1sd |
#### Example
```yaml
@@ -46,7 +46,7 @@ Under the `appsvc.registration.synapse` namespace:
| Key | Type | Required | Default | Purpose |
|--------|--------|----------|--------------------|--------------------------------------------------------------------------|
| `id` | string | No | `appservice-mxisd` | The unique, user-defined ID of this application service. See spec. |
| `id` | string | No | `appservice-ma1sd` | The unique, user-defined ID of this application service. See spec. |
| `file` | string | Yes | *None* | If defined, the synapse registration file that should be created/updated |
##### Example
@@ -54,17 +54,17 @@ Under the `appsvc.registration.synapse` namespace:
appsvc:
registration:
synapse:
file: '/etc/matrix-synapse/mxisd-appservice-registration.yaml'
file: '/etc/matrix-synapse/ma1sd-appservice-registration.yaml'
```
Edit your `homeserver.yaml` and add a new entry to the appservice config file, which should look something like this:
```yaml
app_service_config_files:
- '/etc/matrix-synapse/mxisd-appservice-registration.yaml'
- '/etc/matrix-synapse/ma1sd-appservice-registration.yaml'
- ...
```
Restart synapse when done to register mxisd.
Restart synapse when done to register ma1sd.
#### Others
See your Homeserver documentation on how to integrate.
@@ -86,9 +86,9 @@ appsvc:
#### Use
The following steps assume:
- `matrix.domain` set to `example.org`
- `appsvc.user.main` set to `mxisd` or not set
- `appsvc.user.main` set to `ma1sd` or not set
1. Invite `@mxisd:example.org` to a new direct chat
1. Invite `@ma1sd:example.org` to a new direct chat
2. Type `!help` to get all available commands
### Email Notification about room invites by Matrix IDs
@@ -100,7 +100,7 @@ account was already provisioned on the Homeserver.
- At least one email entry in the identity store for each user that could be invited.
#### Configuration
In your mxisd config file:
In your ma1sd config file:
```yaml
synapseSql:
enabled: false ## Do not use this line if Synapse is used as an Identity Store

10
docs/features/federation.md
View File

@@ -5,7 +5,7 @@ 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 can be configured to talk to fallback Identity servers like
For 3PIDs which are not compatible with the DNS system, ma1sd can be configured to talk to fallback Identity servers like
the central matrix.org one. See the [Identity feature](identity.md#lookups) for instructions on how to enable it.
Outbound federation is enabled by default while inbound federation is opt-in and require a specific DNS record.
@@ -13,7 +13,7 @@ Outbound federation is enabled by default while inbound federation is opt-in and
## Overview
```
+-------------------+ +-------------> +----------+
| mxisd | | | Backends |
| ma1sd | | | Backends |
| | | +------> +----------+
| | | |
| Invites / Lookups | | |
@@ -23,7 +23,7 @@ Outbound federation is enabled by default while inbound federation is opt-in and
| | |
| +--------+ | | +-------------------+
Homeserver --->| Local |>------------------+------> | Remote Federated |
and clients | +--------+ | | mxisd servers |
and clients | +--------+ | | ma1sd servers |
+-------------------+ +-------------------+
```
@@ -34,11 +34,11 @@ If you would like to be reachable for lookups over federation, create the follow
_matrix-identity._tcp.example.com. 3600 IN SRV 10 0 443 matrix.example.com.
```
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.
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 ma1sd.
## 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:
use the following ma1sd configuration options:
```yaml
lookup:
recursive:

12
docs/features/identity.md
View File

@@ -17,7 +17,7 @@ forward:
- 'matrix-org'
```
**NOTE:** You should carefully consider enabling this option, which is discouraged.
For more info, see the [relevant issue](https://github.com/kamax-matrix/mxisd/issues/76).
For more info, see the [relevant issue](https://github.com/kamax-matrix/ma1sd/issues/76).
## Invitations
### Expiration
@@ -25,10 +25,10 @@ For more info, see the [relevant issue](https://github.com/kamax-matrix/mxisd/is
Matrix does not provide a mean to remove/cancel pending 3PID invitations with the APIs. The current reference
implementations also do not provide any mean to do so. This leads to 3PID invites forever stuck in rooms.
To provide this functionality, mxisd uses a workaround: resolve the invite to a dedicated User ID, which can be
controlled by mxisd or a bot/service that will then reject the invite.
To provide this functionality, ma1sd uses a workaround: resolve the invite to a dedicated User ID, which can be
controlled by ma1sd or a bot/service that will then reject the invite.
If this dedicated User ID is to be controlled by mxisd, the [Application Service](experimental/application-service.md)
If this dedicated User ID is to be controlled by ma1sd, the [Application Service](experimental/application-service.md)
feature must be configured and integrated with your Homeserver, as well as the *Auto-reject 3PID invite capability*.
#### Configuration
@@ -63,7 +63,7 @@ It's a middle ground between a closed server, where every user must be created o
and an open server, where anyone can register.
#### Integration
Because Identity Servers do not control 3PID invites as per Matrix spec, mxisd needs to intercept a set of Homeserver
Because Identity Servers do not control 3PID invites as per Matrix spec, ma1sd needs to intercept a set of Homeserver
endpoints to apply the policies.
##### Reverse Proxy
@@ -101,7 +101,7 @@ Resolution of 3PID invitations can be customized using the following configurati
`invite.resolution.timer`
- Default value: `1`
- Description: How often, in minutes, mxisd should try to resolve pending invites.
- Description: How often, in minutes, ma1sd should try to resolve pending invites.
## 3PIDs Management
See the [3PID session documents](../threepids/session)

4
docs/features/registration.md
View File

@@ -13,7 +13,7 @@
## Overview
**NOTE**: This feature is beta: it is considered stable enough for production but is incomplete and may contain bugs.
Registration is an enhanced feature of mxisd to control registrations involving 3PIDs on a Homeserver based on policies:
Registration is an enhanced feature of ma1sd to control registrations involving 3PIDs on a Homeserver based on policies:
- Match pending 3PID invites on the server
- Match 3PID pattern, like a specific set of domains for emails
- In further releases, use 3PIDs found in Identity stores
@@ -28,7 +28,7 @@ As such, it relies on the homeserver to require 3PIDs with the registration flow
This feature is not part of the Matrix Identity Server spec.
## Integration
mxisd needs to be integrated at several levels for this feature to work:
ma1sd needs to be integrated at several levels for this feature to work:
- Reverse proxy: intercept the 3PID register endpoints and act on them
- Homeserver: require 3PID to be part of the registration data