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

Continue structural port from Spring Boot to Undertow

Browse Source 
- Configuration options
- Configuration documentation
This commit is contained in:
Max Dor
2018-12-31 15:07:49 +01:00
parent ace5918342
commit 4185b644b7
48 changed files with 454 additions and 351 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -7,8 +7,8 @@ out/
.idea/
# Local dev config
/application.yaml
/mxisd.yaml
/application.yaml
# Local dev storage
/mxisd.db

3
docs/README.md
View File

@@ -5,6 +5,7 @@
- Installation
- [Debian package](install/debian.md)
- [ArchLinux](install/archlinux.md)
- [NixOS](install/nixos.md)
- [Docker](install/docker.md)
- [From source](install/source.md)
- [Architecture overview](architecture.md)
@@ -22,4 +23,4 @@
- [SendGrid](threepids/notification/sendgrid-handler.md)
- [Sessions](threepids/session/session.md)
- [Views](threepids/session/session-views.md)
- [FAQ](faq.md)
- [FAQ](faq.md)

2
docs/build.md
View File

@@ -29,12 +29,14 @@ java -jar build/libs/mxisd.jar
Ensure the signing key is available:
```bash
$ curl 'http://localhost:8090/_matrix/identity/api/v1/pubkey/ed25519:0'
{"public_key":"..."}
```
Test basic recursive lookup (requires Internet connection with access to TCP 443):
```bash
$ curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=mxisd-federation-test@kamax.io'
{"address":"mxisd-federation-test@kamax.io","medium":"email","mxid":"@mxisd-lookup-test:kamax.io",...}
```

50
docs/configure.md
View File

@@ -1,7 +1,6 @@
# Configuration
- [Concepts](#concepts)
- [Syntax](#syntax)
- [Variables](#variables)
- [Matrix](#matrix)
- [Server](#server)
- [Storage](#storage)
@@ -11,36 +10,15 @@
## Concepts
### Syntax
The configuration file is [YAML](http://yaml.org/) based, allowing two types of syntax.
Properties-like:
```yaml
my.config.item: 'value'
```
Object-like:
The configuration file is [YAML](http://yaml.org/) based:
```yaml
my:
config:
item: 'value'
```
These can also be combined within the same file.
Both syntax will be used interchangeably in these documents.
### Variables
It is possible to copy the value of a configuration item into another using the syntax `${config.key.item}`.
Example that will copy the value of `matrix.domain` into `server.name`:
```yaml
matrix:
domain: 'example.org'
server:
name: '${matrix.domain}'
```
**WARNING:** mxisd might overwrite/adapt some values during launch. Those changes will not be reflected into copied keys.
When referencing keys in all documents, a property-like shorthand will be used. The shorthand for the above example would be `my.config.item`
## Matrix
`matrix.domain`
@@ -53,10 +31,12 @@ Namespace to create arbitrary list of Identity servers, usable in other parts of
Example:
```yaml
matrix.identity.servers:
myOtherServers:
- 'https://other1.example.org'
- 'https://other2.example.org'
matrix:
identity:
servers:
myOtherServers:
- 'https://other1.example.org'
- 'https://other2.example.org'
```
Create a list under the label `root` containing a single Identity server, `https://matrix.org`
@@ -82,19 +62,23 @@ See the dedicated documents:
Example:
```yaml
notification.handler.email: 'sendgrid'
notification.handler.msisdn: 'raw'
notification:
handler:
email: 'sendgrid'
msisdn: 'raw'
```
- Emails notifications would use the `sendgrid` handler, which define its own configuration under `notification.handlers.sendgrid`
- Phone notification would use the `raw` handler, basic default built-in handler of mxisd
- Phone notification would use the `raw` handler, basic default built-in handler in mxisd
### Handlers
- `notification.handers.<handler ID>`: Handler-specific configuration for the given handler ID. Repeatable.
Example:
```yaml
notification.handlers.raw: ...
notification.handlers.sendgrid: ...
notification:
handlers:
raw: ...
sendgrid: ...
```
Built-in:

9
docs/features/authentication.md
View File

@@ -151,9 +151,12 @@ the internal IP of the Homeserver so it can talk to it directly to integrate its
To do so, put the following configuration in your mxisd configuration:
```yaml
dns.overwrite.homeserver.client:
- name: 'example.org'
value: 'http://localhost:8008'
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.
You can use `${server.name}` to auto-populate the `value` using the `server.name` configuration option and avoid duplicating it.

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

@@ -5,16 +5,19 @@ 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
You can also look at our [Email Bridge README](https://github.com/kamax-matrix/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>
lookup:
recursive:
bridge:
enabled: <boolean>
recursiveOnly: <boolean>
server: <URL to the bridge endpoint for all 3PID medium>
mappings:
<3PID MEDIUM HERE>: <URL to dedicated bridge for that medium>
```

24
docs/features/directory.md
View File

@@ -123,27 +123,31 @@ the internal IP of the Homeserver so it can talk to it directly to integrate its
To do so, use the following configuration:
```yaml
dns.overwrite.homeserver.client:
- name: 'example.org'
value: 'http://localhost:8008'
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.
`value` is the base internal URL of the Homeserver, without any `/_matrix/..` or trailing `/`.
- `name` must be the hostname of the URL that clients use when connecting to the Homeserver.
- `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 configuration file:
```yaml
directory.exclude.homeserver: true
directory:
exclude:
homeserver: true
```
### 3PID exclusion in search
You can configure if the 3PID should also be included when doing a directory search.
By default, a search is performed on the 3PIDs. If you would like to not include them:
```yaml
directory.exclude.threepid: true
directory:
exclude:
threepid: true
```

19
docs/features/federation.md
View File

@@ -40,10 +40,21 @@ The port must be HTTPS capable which is what you get in a regular setup with a r
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
lookup:
recursive:
enabled: false
invite:
resolution:
recursive: false
session:
policy:
validation:
forLocal:
toRemote:
enabled: false
forRemote:
toRemote:
enabled: false
```
There is currently no way to selectively disable federation towards specific servers, but this feature is planned.

5
docs/features/identity.md
View File

@@ -7,8 +7,9 @@ Implementation of the [Unofficial Matrix Identity Service API](https://kamax.io/
If you would like to use the central matrix.org Identity server to ensure maximum discovery at the cost of potentially
leaking all your contacts information, add the following to your configuration:
```yaml
forward.servers:
- 'matrix-org'
forward:
servers:
- '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).

2
docs/features/profile.md
View File

@@ -7,4 +7,4 @@ Currently supported:
- 3PIDs
- Roles/Groups
Experimental sub-features are also available. See [the dedicated document](experimental/profile.md).
Experimental sub-features are also available. See [the dedicated document](experimental/profile.md).

15
docs/getting-started.md
View File

@@ -38,13 +38,20 @@ Install via:
See the [Latest release](https://github.com/kamax-matrix/mxisd/releases/latest) for links to each.
## Configure
**NOTE**: please view the install instruction for your platform, as this step might be optional or already handled for you.
> **NOTE**: Please view the install instruction for your platform, as this step might be optional or already handled for you.
> **NOTE**: Details about configuration syntax and format are described [here](configure.md)
Create/edit a minimal configuration (see installer doc for the location):
```yaml
matrix.domain: 'example.org'
key.path: '/path/to/signing.key.file'
storage.provider.sqlite.database: '/path/to/mxisd.db'
matrix:
domain: 'example.org'
key:
path: '/path/to/signing.key.file'
storage:
provider:
sqlite:
database: '/path/to/mxisd.db'
```
- `matrix.domain` should be set to your Homeserver domain (`server_name` in synapse configuration)
- `key.path` will store the signing keys, which must be kept safe! If the file does not exist, keys will be generated for you.

2
docs/install/source.md
View File

@@ -26,7 +26,7 @@ chmod a+x /opt/mxisd/mxisd.jar
# Create symlink for easy exec
ln -s /opt/mxisd/mxisd.jar /usr/bin/mxisd
```
2. Copy the sample config file `./application.example.yaml` to `/etc/opt/mxisd/mxisd.yaml`, edit to your needs
2. Copy the sample config file `./mxisd.example.yaml` to `/etc/opt/mxisd/mxisd.yaml`, edit to your needs
3. Copy `src/systemd/mxisd.service` to `/etc/systemd/system/` and edit if needed
4. Enable service for auto-startup
```bash

78
docs/stores/exec.md
View File

@@ -68,7 +68,8 @@ We will use the term `Executable` for each lookup/action and `Processor` for eac
### Global
```yaml
exec.enabled: <boolean>
exec:
enabled: <boolean>
```
Enable/disable the Identity store at a global/default level. Each feature can still be individually enabled/disabled.
@@ -79,7 +80,9 @@ Not all features use all tokens, and each feature might also have its own specif
They can be set within the following scope:
```yaml
exec.token.<token>: '<value>'
exec:
token:
<token>: '<value>'
```
---
@@ -184,13 +187,16 @@ The following types are available:
### Examples
#### Basic
```yaml
exec.auth.enabled: true
exec.auth.command: '/opt/mxisd-exec/auth.sh'
exec.auth.args: ['{localpart}']
exec.auth.input.type: 'plain'
exec.auth.input.template: '{password}'
exec.auth.env:
DOMAIN: '{domain}'
exec:
auth:
enabled: true
command: '/opt/mxisd-exec/auth.sh'
args: ['{localpart}']
input:
type: 'plain'
template: '{password}'
env:
DOMAIN: '{domain}'
```
With Authentication enabled, run `/opt/mxisd-exec/auth.sh` when validating credentials, providing:
- A single command-line argument to provide the `localoart` as username
@@ -243,14 +249,17 @@ See each dedicated [Feature](#features) section.
## Authentication
The Authentication feature can be enabled/disabled using:
```yaml
exec.auth.enabled: <true/false>
exec:
auth:
enabled: <true/false>
```
---
This feature provides a single *Executable* under the namespace:
```yaml
exec.auth:
exec:
auth:
...
```
@@ -294,7 +303,9 @@ Default template:
## Directory
The Directory feature can be enabled/disabled using:
```yaml
exec.directory.enabled: <true/false>
exec:
directory:
enabled: <true/false>
```
---
@@ -303,13 +314,19 @@ Two search types configuration namespace are available, using the same input/out
By name:
```yaml
exec.directory.search.byName:
...
exec:
directory:
search:
byName:
...
```
By 3PID:
```yaml
exec.directory.search.byThreepid:
...
exec:
directory:
search:
byThreepid:
...
```
#### Tokens
@@ -386,8 +403,11 @@ The User ID type will default to `localpart` if:
### Bulk lookup
Configuration namespace:
```yaml
exec.identity.lookup.bulk:
...
exec:
identity:
lookup:
bulk:
...
```
#### Tokens
@@ -418,7 +438,9 @@ Same as the [REST Identity Store](rest.md).
## Profile
The Profile feature can be enabled/disabled using:
```yaml
exec.profile.enabled: <true/false>
exec:
profile:
enabled: <true/false>
```
---
@@ -427,20 +449,26 @@ The following *Executable*s namespace are available, share the same input/output
Get Display name:
```yaml
exec.profile.displayName:
...
exec:
profile:
displayName:
...
```
Get 3PIDs:
```yaml
exec.profile.threePid:
...
exec:
profile:
threePid:
...
```
Get Roles:
```yaml
exec.profile.role:
...
exec:
profile:
role:
...
```

18
docs/stores/firebase.md
View File

@@ -19,35 +19,41 @@ If your client is Riot, you will need a custom version.
## Configuration
```yaml
firebase.enabled: <boolean>
firebase:
enabled: <boolean>
```
Enable/disable this identity store.
Example:
```yaml
firebase.enabled: <boolean>
firebase:
enabled: <boolean>
```
---
```yaml
firebase.credentials: <string>
firebase:
credentials: <string>
```
Path to the credentials file provided by Google Firebase to use with an external app.
Example:
```yaml
firebase.credentials: '/path/to/firebase/credentials.json'
firebase:
credentials: '/path/to/firebase/credentials.json'
```
---
```yaml
firebase.database: <string>
firebase:
database: <string>
```
URL to your Firebase database.
Example:
```yaml
firebase.database: 'https://my-project.firebaseio.com/'
firebase:
database: 'https://my-project.firebaseio.com/'
```

63
docs/stores/ldap.md
View File

@@ -19,13 +19,15 @@ For NetIQ, replace all the `ldap` prefix in the configuration by `netiq`.
### Base
To use your LDAP backend, add the bare minimum configuration in mxisd config file:
```yaml
ldap.enabled: true
ldap.connection.host: 'ldapHostnameOrIp'
ldap.connection.port: 389
ldap.connection.bindDn: 'CN=My Mxisd User,OU=Users,DC=example,DC=org'
ldap.connection.bindPassword: 'TheUserPassword'
ldap.connection.baseDNs:
- 'OU=Users,DC=example,DC=org'
ldap:
enabled: true
connection:
host: 'ldapHostnameOrIp'
port: 389
bindDn: 'CN=My Mxisd User,OU=Users,DC=example,DC=org'
bindPassword: 'TheUserPassword'
baseDNs:
- 'OU=Users,DC=example,DC=org'
```
These are standard LDAP connection configuration. mxisd will try to connect on port default port 389 without encryption.
@@ -34,14 +36,17 @@ If you would like to use several Base DNs, simply add more entries under `baseDN
### TLS/SSL connection
If you would like to use a TLS/SSL connection, use the following configuration options (STARTLS not supported):
```yaml
ldap.connection.tls: true
ldap.connection.port: 12345
ldap:
connection:
tls: true
port: 12345
```
### Filter results
You can also set a default global filter on any LDAP queries:
```yaml
ldap.filter: '(memberOf=CN=My Matrix Users,OU=Groups,DC=example,DC=org)'
ldap:
filter: '(memberOf=CN=My Matrix Users,OU=Groups,DC=example,DC=org)'
```
This example would only return users part of the group called `My Matrix Users`.
This can be overwritten or append in each specific flow describe below.
@@ -64,8 +69,11 @@ most certainly configure those mappings.
The following example would set the `sAMAccountName` attribute as a Matrix User ID localpart:
```yaml
ldap.attribute.uid.type: 'uid'
ldap.attribute.uid.value: 'sAMAccountName'
ldap:
attribute:
uid:
type: 'uid'
value: 'sAMAccountName'
```
#### Display name
@@ -73,7 +81,9 @@ Use `ldap.attribute.name`.
The following example would set the display name to the value of the `cn` attribute:
```yaml
ldap.attribute.name: 'cn'
ldap:
attribute:
name: 'cn'
```
#### 3PIDs
@@ -82,13 +92,15 @@ You can also change the attribute lists for 3PID, like email or phone numbers.
The following example would overwrite the [default list of attributes](../../src/main/resources/application.yaml#L67)
for emails and phone number:
```yaml
ldap.attribute.threepid.email:
- 'mail'
- 'otherMailAttribute'
ldap.attribute.threepid.msisdn:
- 'phone'
- 'otherPhoneAttribute'
ldap:
attribute:
threepid:
email:
- 'mail'
- 'otherMailAttribute'
msisdn:
- 'phone'
- 'otherPhoneAttribute'
```
## Features
@@ -117,8 +129,11 @@ To set a specific filter applied during directory search, use `ldap.directory.fi
If you would like to use extra attributes in search that are not 3PIDs, like nicknames, group names, employee number:
```yaml
ldap.directory.attribute.other:
- 'myNicknameAttribute'
- 'memberOf'
- 'employeeNumberAttribute'
ldap:
directory:
attribute:
other:
- 'myNicknameAttribute'
- 'memberOf'
- 'employeeNumberAttribute'
```

57
docs/stores/sql.md
View File

@@ -15,19 +15,21 @@
Due to the implementation complexity of supporting arbitrary hashing/encoding mechanisms or auth flow, Authentication
will be out of scope of SQL Identity stores and should be done via one of the other identity stores, typically
the [REST Identity store](rest.md).
the [Exec Identity Store](exec.md) or the [REST Identity Store](rest.md).
## Configuration
### Basic
```yaml
sql.enabled: <boolean>
sql:
enabled: <boolean>
```
Enable/disable the identity store
---
```yaml
sql.type: <string>
sql:
type: <string>
```
Set the SQL backend to use:
- `sqlite`
@@ -38,14 +40,16 @@ Set the SQL backend to use:
### Connection
#### SQLite
```yaml
sql.connection: <string>
sql:
connection: <string>
```
Set the value to the absolute path to the Synapse SQLite DB file.
Example: `/path/to/sqlite/file.db`
#### Others
```yaml
sql.connection: //<HOST[:PORT]/DB?user=USER&password=PASS
sql:
connection: //<HOST[:PORT]/DB?user=USER&password=PASS
```
Set the connection info for the database by replacing the following values:
- `HOST`: Hostname of the SQL server
@@ -58,20 +62,23 @@ This follow the JDBC URI syntax. See [official website](https://docs.oracle.com/
### Directory
```yaml
sql.directory.enabled: false
sql:
directory:
enabled: false
```
---
```yaml
sql.directory.query:
name:
type: <string>
value: <string>
threepid:
type: <string>
value: <string>
sql:
directory:
query:
name:
type: <string>
value: <string>
threepid:
type: <string>
value: <string>
```
For each query, `type` can be used to tell mxisd how to process the ID column:
- `localpart` will append the `matrix.domain` to it
@@ -83,17 +90,21 @@ For each query, `type` can be used to tell mxisd how to process the ID column:
Example:
```yaml
sql.directory.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 ?'
sql:
directory:
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 ?'
```
### Identity
```yaml
sql.identity.type: <string>
sql.identity.query: <string>
sql:
identity:
type: <string>
query: <string>
```

12
docs/stores/synapse.md
View File

@@ -14,14 +14,16 @@ Authentication is done by Synapse itself.
## Configuration
### Basic
```yaml
synapseSql.enabled: <boolean>
synapseSql:
enabled: <boolean>
```
Enable/disable the identity store
---
```yaml
synapseSql.type: <string>
synapseSql:
type: <string>
```
Set the SQL backend to use which is configured in synapse:
- `sqlite`
@@ -29,14 +31,16 @@ Set the SQL backend to use which is configured in synapse:
### SQLite
```yaml
synapseSql.connection: <string>
synapseSql:
connection: <string>
```
Set the value to the absolute path to the Synapse SQLite DB file.
Example: `/path/to/synapse/sqliteFile.db`
### PostgreSQL
```yaml
synapseSql.connection: //<HOST[:PORT]/DB?user=USER&password=PASS
synapseSql:
connection: //<HOST[:PORT]/DB?user=USER&password=PASS
```
Set the connection info for the database by replacing the following values:
- `HOST`: Hostname of the SQL server

19
docs/stores/wordpress.md
View File

@@ -34,22 +34,29 @@ If this is not the case for your installation, the mxisd URL will need to be app
### mxisd
Enable in the configuration:
```yaml
wordpress.enabled: true
wordpress:
enabled: true
```
Configure the URL to your Wordpress installation - see above about added `/index.php`:
```yaml
wordpress.rest.base: 'http://localhost:8080'
wordpress:
rest:
base: 'http://localhost:8080'
```
Configure the SQL connection to your Wordpress database:
```yaml
wordpress.sql.connection: '//127.0.0.1/wordpress?user=root&password=example'
wordpress:
sql:
connection: '//127.0.0.1/wordpress?user=root&password=example'
```
---
By default, MySQL database is expected. If you use another database, use:
```yaml
wordpress.sql.type: <string>
wordpress:
sql:
type: <string>
```
With possible values:
- `mysql`
@@ -61,6 +68,8 @@ With possible values:
To configure the tables prefix for default queries, in case a custom value was set during Wordpress install:
```yaml
wordpress.sql.tablePrefix: <string>
wordpress:
sql:
tablePrefix: <string>
```
By default, the value is set to `wp_`.

24
docs/threepids/medium/email/smtp-connector.md
View File

@@ -5,15 +5,17 @@ Connector ID: `smtp`
## Configuration
```yaml
threepid.medium.email:
identity:
from: 'identityServerEmail@example.org'
name: 'My Identity Server'
connectors:
smtp:
host: 'smtpHostname'
port: 587
tls: 1 # 0 = no STARTLS, 1 = try, 2 = force
login: 'smtpLogin'
password: 'smtpPassword'
threepid:
medium:
email:
identity:
from: 'identityServerEmail@example.org'
name: 'My Identity Server'
connectors:
smtp:
host: 'smtpHostname'
port: 587
tls: 1 # 0 = no STARTLS, 1 = try, 2 = force
login: 'smtpLogin'
password: 'smtpPassword'
```

11
docs/threepids/medium/msisdn/twilio-connector.md
View File

@@ -5,7 +5,12 @@ Connector ID: `twilio`
## Configuration
```yaml
threepid.medium.msisdn.connectors.twilio.accountSid: 'myAccountSid'
threepid.medium.msisdn.connectors.twilio.authToken: 'myAuthToken'
threepid.medium.msisdn.connectors.twilio.number: '+123456789'
threepid:
medium:
msisdn:
connectors:
twilio:
accountSid: 'myAccountSid'
authToken: 'myAuthToken'
number: '+123456789'
```

25
docs/threepids/notification/basic-handler.md
View File

@@ -18,20 +18,23 @@ This handler can be used with the 3PID types:
## Configuration
Enabled by default or with:
```yaml
notification.handler.email: 'raw'
notification:
handler:
email: 'raw'
```
**WARNING:** Will be consolidated soon, prone to breaking changes.
Structure and default values:
```yaml
threepid.medium:
email:
identity:
from: ''
name: ''
connector: 'smtp'
generator: 'template'
msisdn:
connector: 'twilio'
generator: 'template'
threepid:
medium:
email:
identity:
from: ''
name: ''
connector: 'smtp'
generator: 'template'
msisdn:
connector: 'twilio'
generator: 'template'
```

38
docs/threepids/notification/sendgrid-handler.md
View File

@@ -1,7 +1,39 @@
# SendGrid Notification handler
To be completed. See [raw possible configuration items](https://github.com/kamax-matrix/mxisd/blob/master/src/main/resources/application.yaml#L172).
> **WARNING:** This section is incomplete and may be misleading. Contact us if guidance is needed.
Enabled with:
Enable with:
```yaml
notification.handler.email: 'sendgrid'
notification:
handler:
email: 'sendgrid'
```
Available Configuration keys:
```yaml
notification:
handlers:
sendgrid:
api:
key: <API key>
identity:
from: <Sender email address>
name: <Sender name>
templates:
invite:
subject: <Subject of the email notification sent for room invites>
body:
text: <Path to file containing the raw text part of the email. Do not set to not use one>
html: <Path to file containing the HTML part of the email. Do not set to not use one>
session:
validation:
local:
subject: <Subject of the email notification sent for local 3PID sessions>
body:
text: <Path to file containing the raw text part of the email. Do not set to not use one>
html: <Path to file containing the HTML part of the email. Do not set to not use one>
remote:
subject: <Subject of the email notification sent for remote 3PID sessions>
body:
text: <Path to file containing the raw text part of the email. Do not set to not use one>
html: <Path to file containing the HTML part of the email. Do not set to not use one>
```

22
docs/threepids/notification/template-generator.md
View File

@@ -11,16 +11,18 @@ placeholders and also have their own individual set of placeholders.
## Configuration
To configure paths to the various templates:
```yaml
threepid.medium.<YOUR 3PID MEDIUM HERE>:
generators:
template:
invite: '/path/to/invite-template.eml'
session:
validation:
local: '/path/to/validate-local-template.eml'
remote: 'path/to/validate-remote-template.eml'
generic:
matrixId: '/path/to/mxid-invite-template.eml'
threepid:
medium:
<YOUR 3PID MEDIUM HERE>:
generators:
template:
invite: '/path/to/invite-template.eml'
session:
validation:
local: '/path/to/validate-local-template.eml'
remote: 'path/to/validate-remote-template.eml'
generic:
matrixId: '/path/to/mxid-invite-template.eml'
```
The `template` generator is usually the default, so no further configuration is needed.

32
docs/threepids/session/session-views.md
View File

@@ -6,21 +6,23 @@ Pseudo-configuration to illustrate the structure:
```yaml
# CONFIGURATION EXAMPLE
# DO NOT COPY/PASTE THIS IN YOUR CONFIGURATION
view.session.local:
onTokenSubmit:
success: '/path/to/session/local/tokenSubmitSuccess-page.html'
failure: '/path/to/session/local/tokenSubmitFailure-page.html'
view.session.localRemote:
onTokenSubmit:
success: '/path/to/session/localRemote/tokenSubmitSuccess-page.html'
failure: '/path/to/session/local/tokenSubmitFailure-page.html'
view.session.remote:
onRequest:
success: '/path/to/session/remote/requestSuccess-page.html'
failure: '/path/to/session/remote/requestFailure-page.html'
onCheck:
success: '/path/to/session/remote/checkSuccess-page.html'
failure: '/path/to/session/remote/checkFailure-page.html'
view:
session:
local:
onTokenSubmit:
success: '/path/to/session/local/tokenSubmitSuccess-page.html'
failure: '/path/to/session/local/tokenSubmitFailure-page.html'
localRemote:
onTokenSubmit:
success: '/path/to/session/localRemote/tokenSubmitSuccess-page.html'
failure: '/path/to/session/local/tokenSubmitFailure-page.html'
remote:
onRequest:
success: '/path/to/session/remote/requestSuccess-page.html'
failure: '/path/to/session/remote/requestFailure-page.html'
onCheck:
success: '/path/to/session/remote/checkSuccess-page.html'
failure: '/path/to/session/remote/checkFailure-page.html'
# CONFIGURATION EXAMPLE
# DO NOT COPY/PASTE THIS IN YOUR CONFIGURATION
```

84
docs/threepids/session/session.md
View File

@@ -133,19 +133,22 @@ file unless you want to specifically overwrite them.
```yaml
# CONFIGURATION EXAMPLE
# DO NOT COPY/PASTE THIS IN YOUR CONFIGURATION
session.policy.validation.enabled: true
session.policy.validation.forLocal:
enabled: true
toLocal: true
toRemote:
enabled: true
server: 'configExample' # Not to be included in config! Already present in default config!
session.policy.validation.forRemote:
enabled: true
toLocal: true
toRemote:
enabled: true
server: 'configExample' # Not to be included in config! Already present in default config!
session:
policy:
validation:
enabled: true
forLocal:
enabled: true
toLocal: true
toRemote:
enabled: true
server: 'configExample' # Not to be included in config! Already present in default config!
forRemote:
enabled: true
toLocal: true
toRemote:
enabled: true
server: 'configExample' # Not to be included in config! Already present in default config!
# DO NOT COPY/PASTE THIS IN YOUR CONFIGURATION
# CONFIGURATION EXAMPLE
```
@@ -219,17 +222,20 @@ On the flip side, people with *Remote* 3PID scopes will not be found from other
Use the following values:
```yaml
session.policy.validation.enabled: true
session.policy.validation.forLocal:
enabled: true
toLocal: true
toRemote:
enabled: false
session.policy.validation.forRemote:
enabled: true
toLocal: true
toRemote:
enabled: false
session:
policy:
validation:
enabled: true
forLocal:
enabled: true
toLocal: true
toRemote:
enabled: false
forRemote:
enabled: true
toLocal: true
toRemote:
enabled: false
```
**IMPORTANT**: When using local-only mode and if you are using synapse, you will also need to enable its dedicated Identity
@@ -245,17 +251,20 @@ Typical use cases:
Use the following values:
```yaml
session.policy.validation.enabled: true
session.policy.validation.forLocal:
enabled: true
toLocal: false
toRemote:
enabled: true
session.policy.validation.forRemote:
enabled: true
toLocal: false
toRemote:
enabled: true
session:
policy:
validation:
enabled: true
forLocal:
enabled: true
toLocal: false
toRemote:
enabled: true
forRemote:
enabled: true
toLocal: false
toRemote:
enabled: true
```
#### Sessions disabled
@@ -272,5 +281,8 @@ It is therefore recommended to not fully disable sessions but instead restrict s
Use the following values to enable this mode:
```yaml
session.policy.validation.enabled: false
session:
policy:
validation:
enabled: false
```

58
application.example.yaml → mxisd.example.yaml
View File

@@ -9,7 +9,8 @@
# (note: in Synapse Homeserver, the Matrix domain may be defined as 'server_name' in configuration file).
#
# This is used to build the various identifiers for identity, auth and directory.
matrix.domain: ''
matrix:
domain: ''
################
@@ -24,7 +25,8 @@ matrix.domain: ''
# - /var/lib/mxisd/sign.key
#
# The signing key is auto-generated during execution time if not present.
key.path: ''
key:
path: ''
############################
@@ -44,7 +46,10 @@ key.path: ''
# - /var/local/mxisd/mxisd.db
# - /var/lib/mxisd/mxisd.db
#
storage.provider.sqlite.database: '/path/to/mxisd.db'
storage:
provider:
sqlite:
database: '/path/to/mxisd.db'
####################
@@ -57,7 +62,8 @@ storage.provider.sqlite.database: '/path/to/mxisd.db'
#
# If you would like to use them and trade away your privacy for convenience, uncomment the following option:
#
#forward.servers: ['matrix-org']
#forward:
# servers: ['matrix-org']
################
@@ -88,27 +94,33 @@ storage.provider.sqlite.database: '/path/to/mxisd.db'
# see https://github.com/kamax-matrix/mxisd/blob/master/docs/threepids/notification/template-generator.md
#
#### E-mail invite sender
#
# SMTP host
threepid.medium.email.connectors.smtp.host: "smtp.example.org"
threepid:
medium:
email:
identity:
# The e-mail to send as.
from: "matrix-identity@example.org"
# SMTP port
threepid.medium.email.connectors.smtp.port: 587
connectors:
smtp:
# TLS mode for the connection.
#
# Possible values:
# 0 Disable TLS entirely
# 1 Enable TLS if supported by server (default)
# 2 Force TLS and fail if not available
#
#threepid.medium.email.connectors.smtp.tls: 1
# SMTP host
host: "smtp.example.org"
# Login for SMTP
threepid.medium.email.connectors.smtp.login: "matrix-identity@example.org"
# SMTP port
port: 587
# Password for the account
threepid.medium.email.connectors.smtp.password: "ThePassword"
# TLS mode for the connection.
#
# Possible values:
# 0 Disable TLS entirely
# 1 Enable TLS if supported by server (default)
# 2 Force TLS and fail if not available
#
# tls: 1
# The e-mail to send as.
threepid.medium.email.identity.from: "matrix-identity@example.org"
# Login for SMTP
login: "matrix-identity@example.org"
# Password for the account
password: "ThePassword"

2
src/main/java/io/kamax/mxisd/config/BulkLookupConfig.java
View File

@@ -20,7 +20,6 @@
package io.kamax.mxisd.config;
import javax.annotation.PostConstruct;
import java.util.Objects;
public class BulkLookupConfig {
@@ -35,7 +34,6 @@ public class BulkLookupConfig {
this.enabled = enabled;
}
@PostConstruct
public void build() {
if (Objects.isNull(enabled)) {
enabled = true;

3
src/main/java/io/kamax/mxisd/config/DirectoryConfig.java
View File

@@ -23,8 +23,6 @@ package io.kamax.mxisd.config;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
public class DirectoryConfig {
private final static Logger log = LoggerFactory.getLogger(DirectoryConfig.class);
@@ -63,7 +61,6 @@ public class DirectoryConfig {
this.exclude = exclude;
}
@PostConstruct
public void build() {
log.info("--- Directory config ---");
log.info("Exclude:");

2
src/main/java/io/kamax/mxisd/config/DnsOverwriteConfig.java
View File

@@ -25,7 +25,6 @@ import io.kamax.mxisd.util.GsonUtil;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.util.ArrayList;
import java.util.List;
@@ -89,7 +88,6 @@ public class DnsOverwriteConfig {
this.homeserver = homeserver;
}
@PostConstruct
public void build() {
Gson gson = GsonUtil.build();
log.info("--- DNS Overwrite config ---");

2
src/main/java/io/kamax/mxisd/config/ExecConfig.java
View File

@@ -22,7 +22,6 @@ package io.kamax.mxisd.config;
import org.apache.commons.lang3.StringUtils;
import javax.annotation.PostConstruct;
import java.util.*;
public class ExecConfig {
@@ -512,7 +511,6 @@ public class ExecConfig {
this.profile = profile;
}
@PostConstruct
public ExecConfig build() {
if (Objects.isNull(getAuth().isEnabled())) {
getAuth().setEnabled(isEnabled());

3
src/main/java/io/kamax/mxisd/config/FirebaseConfig.java
View File

@@ -23,8 +23,6 @@ package io.kamax.mxisd.config;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
public class FirebaseConfig {
private transient final Logger log = LoggerFactory.getLogger(FirebaseConfig.class);
@@ -57,7 +55,6 @@ public class FirebaseConfig {
this.database = database;
}
@PostConstruct
public void build() {
log.info("--- Firebase configuration ---");
log.info("Enabled: {}", isEnabled());

3
src/main/java/io/kamax/mxisd/config/InvitationConfig.java
View File

@@ -24,8 +24,6 @@ import io.kamax.mxisd.util.GsonUtil;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
public class InvitationConfig {
private transient final Logger log = LoggerFactory.getLogger(InvitationConfig.class);
@@ -63,7 +61,6 @@ public class InvitationConfig {
this.resolution = resolution;
}
@PostConstruct
public void build() {
log.info("--- Invite config ---");
log.info("Resolution: {}", GsonUtil.build().toJson(resolution));

3
src/main/java/io/kamax/mxisd/config/KeyConfig.java
View File

@@ -23,8 +23,6 @@ package io.kamax.mxisd.config;
import io.kamax.mxisd.exception.ConfigurationException;
import org.apache.commons.lang.StringUtils;
import javax.annotation.PostConstruct;
public class KeyConfig {
private String path;
@@ -37,7 +35,6 @@ public class KeyConfig {
return path;
}
@PostConstruct
public void build() {
if (StringUtils.isBlank(getPath())) {
throw new ConfigurationException("key.path");

33
src/main/java/io/kamax/mxisd/config/ListenerConfig.java
View File

@@ -20,9 +20,9 @@
package io.kamax.mxisd.config;
import io.kamax.mxisd.exception.ConfigurationException;
import org.apache.commons.lang.StringUtils;
import javax.annotation.PostConstruct;
import java.net.MalformedURLException;
import java.net.URL;
@@ -80,24 +80,27 @@ public class ListenerConfig {
this.token = token;
}
@PostConstruct
public void build() throws MalformedURLException {
if (StringUtils.isBlank(url)) {
return;
}
public void build() {
try {
if (StringUtils.isBlank(url)) {
return;
}
csUrl = new URL(url);
csUrl = new URL(url);
if (StringUtils.isBlank(getLocalpart())) {
throw new IllegalArgumentException("localpart for matrix listener is not set");
}
if (StringUtils.isBlank(getLocalpart())) {
throw new IllegalArgumentException("localpart for matrix listener is not set");
}
if (StringUtils.isBlank(getToken().getAs())) {
throw new IllegalArgumentException("AS token is not set");
}
if (StringUtils.isBlank(getToken().getAs())) {
throw new IllegalArgumentException("AS token is not set");
}
if (StringUtils.isBlank(getToken().getHs())) {
throw new IllegalArgumentException("HS token is not set");
if (StringUtils.isBlank(getToken().getHs())) {
throw new IllegalArgumentException("HS token is not set");
}
} catch (MalformedURLException e) {
throw new ConfigurationException(e);
}
}

4
src/main/java/io/kamax/mxisd/config/MatrixConfig.java
View File

@@ -26,7 +26,6 @@ import org.apache.commons.lang.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
@@ -90,7 +89,6 @@ public class MatrixConfig {
this.listener = listener;
}
@PostConstruct
public void build() {
log.info("--- Matrix config ---");
@@ -101,6 +99,8 @@ public class MatrixConfig {
log.info("Domain: {}", getDomain());
log.info("Identity:");
log.info("\tServers: {}", GsonUtil.get().toJson(identity.getServers()));
listener.build();
}
}

2
src/main/java/io/kamax/mxisd/config/RecursiveLookupBridgeConfig.java
View File

@@ -23,7 +23,6 @@ package io.kamax.mxisd.config;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.util.HashMap;
import java.util.Map;
@@ -68,7 +67,6 @@ public class RecursiveLookupBridgeConfig {
this.mappings = mappings;
}
@PostConstruct
public void build() {
log.info("--- Bridge integration lookups config ---");
log.info("Enabled: {}", getEnabled());

2
src/main/java/io/kamax/mxisd/config/ServerConfig.java
View File

@@ -24,7 +24,6 @@ import org.apache.commons.lang.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.net.MalformedURLException;
import java.net.URL;
@@ -60,7 +59,6 @@ public class ServerConfig {
this.publicUrl = publicUrl;
}
@PostConstruct
public void build() {
log.info("--- Server config ---");

3
src/main/java/io/kamax/mxisd/config/SessionConfig.java
View File

@@ -24,8 +24,6 @@ import io.kamax.matrix.json.GsonUtil;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
public class SessionConfig {
private transient final Logger log = LoggerFactory.getLogger(SessionConfig.class);
@@ -162,7 +160,6 @@ public class SessionConfig {
this.policy = policy;
}
@PostConstruct
public void build() {
log.info("--- Session config ---");
log.info("Global Policy: {}", GsonUtil.get().toJson(policy));

3
src/main/java/io/kamax/mxisd/config/StorageConfig.java
View File

@@ -23,8 +23,6 @@ package io.kamax.mxisd.config;
import io.kamax.mxisd.exception.ConfigurationException;
import org.apache.commons.lang.StringUtils;
import javax.annotation.PostConstruct;
public class StorageConfig {
public static class Provider {
@@ -60,7 +58,6 @@ public class StorageConfig {
this.provider = provider;
}
@PostConstruct
public void build() {
if (StringUtils.isBlank(getBackend())) {
throw new ConfigurationException("storage.backend");

3
src/main/java/io/kamax/mxisd/config/ViewConfig.java
View File

@@ -24,8 +24,6 @@ import io.kamax.matrix.json.GsonUtil;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
public class ViewConfig {
private transient final Logger log = LoggerFactory.getLogger(ViewConfig.class);
@@ -145,7 +143,6 @@ public class ViewConfig {
this.session = session;
}
@PostConstruct
public void build() {
log.info("--- View config ---");
log.info("Session: {}", GsonUtil.get().toJson(session));

5
src/main/java/io/kamax/mxisd/config/ldap/LdapConfig.java
View File

@@ -28,7 +28,6 @@ import org.apache.commons.lang.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.util.*;
public abstract class LdapConfig {
@@ -58,12 +57,11 @@ public abstract class LdapConfig {
public static class Attribute {
private UID uid;
private UID uid = new UID();
private String name = "displayName";
private Map<String, List<String>> threepid = new HashMap<>();
public Attribute() {
uid = new UID();
uid.setType("uid");
uid.setValue("saMAccountName");
@@ -358,7 +356,6 @@ public abstract class LdapConfig {
this.profile = profile;
}
@PostConstruct
public void build() {
log.info("--- " + getConfigName() + " Config ---");
log.info("Enabled: {}", isEnabled());

4
src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java
View File

@@ -25,7 +25,6 @@ import org.apache.commons.lang.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Objects;
@@ -93,7 +92,7 @@ public class RestBackendConfig {
private String auth = "/_mxisd/backend/api/v1/auth/login";
private String directory = "/_mxisd/backend/api/v1/directory/user/search";
private IdentityEndpoints identity = new IdentityEndpoints();
private ProfileEndpoints profile;
private ProfileEndpoints profile = new ProfileEndpoints();
public String getAuth() {
return auth;
@@ -177,7 +176,6 @@ public class RestBackendConfig {
return getHost() + endpoint;
}
@PostConstruct
public void build() {
log.info("--- REST backend config ---");
log.info("Enabled: {}", isEnabled());

6
src/main/java/io/kamax/mxisd/config/sql/SqlConfig.java
View File

@@ -291,15 +291,15 @@ public abstract class SqlConfig {
protected abstract String getProviderName();
public void build() {
if (getAuth().isEnabled() == null) {
if (Objects.isNull(getAuth().isEnabled())) {
getAuth().setEnabled(isEnabled());
}
if (getDirectory().isEnabled() == null) {
if (Objects.isNull(getDirectory().isEnabled())) {
getDirectory().setEnabled(isEnabled());
}
if (getIdentity().isEnabled() == null) {
if (Objects.isNull(getIdentity().isEnabled())) {
getIdentity().setEnabled(isEnabled());
}

6
src/main/java/io/kamax/mxisd/config/threepid/connector/EmailSendGridConfig.java
View File

@@ -25,7 +25,6 @@ import org.apache.commons.lang.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.util.HashMap;
import java.util.Map;
@@ -198,12 +197,13 @@ public class EmailSendGridConfig {
this.templates = templates;
}
@PostConstruct
public void build() {
public EmailSendGridConfig build() {
log.info("--- Email SendGrid connector config ---");
log.info("API key configured?: {}", StringUtils.isNotBlank(api.getKey()));
log.info("Identity: {}", GsonUtil.build().toJson(identity));
log.info("Templates: {}", GsonUtil.build().toJson(templates));
return this;
}
}

2
src/main/java/io/kamax/mxisd/config/threepid/notification/NotificationConfig.java
View File

@@ -27,7 +27,6 @@ import io.kamax.mxisd.threepid.notification.phone.PhoneNotificationHandler;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.util.HashMap;
import java.util.Map;
@@ -59,7 +58,6 @@ public class NotificationConfig {
this.handlers = handlers;
}
@PostConstruct
public void build() {
log.info("--- Notification config ---");
log.info("Handlers:");

4
src/main/java/io/kamax/mxisd/config/wordpress/WordpressConfig.java
View File

@@ -23,7 +23,6 @@ package io.kamax.mxisd.config.wordpress;
import io.kamax.mxisd.exception.ConfigurationException;
import org.apache.commons.lang.StringUtils;
import javax.annotation.PostConstruct;
import java.util.HashMap;
import java.util.Map;
@@ -113,7 +112,7 @@ public class WordpressConfig {
private String type = "mysql";
private String connection;
private String tablePrefix = "wp_";
private Query query;
private Query query = new Query();
public String getType() {
return type;
@@ -177,7 +176,6 @@ public class WordpressConfig {
this.sql = sql;
}
@PostConstruct
public void build() {
if (!isEnabled()) {
return;

2
src/main/java/io/kamax/mxisd/threepid/notification/email/EmailSendGridNotificationHandler.java
View File

@@ -55,7 +55,7 @@ public class EmailSendGridNotificationHandler extends PlaceholderNotificationGen
public EmailSendGridNotificationHandler(MxisdConfig mCfg, EmailSendGridConfig cfg) {
super(mCfg.getMatrix(), mCfg.getServer());
this.cfg = cfg;
this.cfg = cfg.build();
this.sendgrid = new SendGrid(cfg.getApi().getKey());
}

19
src/main/resources/application.yaml
View File

@@ -1,19 +0,0 @@
logging:
level:
org:
springframework: 'WARN'
apache:
catalina: 'WARN'
directory: 'WARN'
io.kamax.mxisd.controller.app.v1.AppServiceController: 'DEBUG'
io.kamax.mxisd.as.AppServiceHandler: 'DEBUG'
pattern:
console: '%d{yyyy-MM-dd HH:mm:ss.SSS} ${LOG_LEVEL_PATTERN:%5p} [%15.15t] %35.35logger{34} : %m%n${LOG_EXCEPTION_CONVERSION_WORD:%wEx}'
---
spring:
profiles: systemd
logging:
pattern:
console: '%d{.SSS} ${LOG_LEVEL_PATTERN:%5p} [%15.15t] %35.35logger{34} : %m%n${LOG_EXCEPTION_CONVERSION_WORD:%wEx}'