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

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
```