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

Lots of new awesome documentation

Browse Source
This commit is contained in:
Maxime Dor
2017-10-02 03:42:23 +02:00
parent 9079bb25cc
commit 4a99ec5531
21 changed files with 849 additions and 538 deletions
Download Patch File Download Diff File Expand all files Collapse all files

372
README.md
View File

@@ -2,218 +2,155 @@ mxisd - Federated Matrix Identity Server Daemon
----- -----
![Travis-CI build status](https://travis-ci.org/kamax-io/mxisd.svg?branch=master) ![Travis-CI build status](https://travis-ci.org/kamax-io/mxisd.svg?branch=master)
[Overview](#overview) | [Features](#features) | [Lookup process](#lookup-process) | [Packages](#packages) | - [Overview](#overview)
[From source](#from-source) | [Configuration](#configuration) | [Network Discovery](#network-discovery) | - [Features](#features)
[Integration](#integration) | [Support](#support) - [Why use mxisd](#why-use-mxisd)
- [Quick start](#quick-start)
- [Support](#support)
- [Contribute](#contribute)
- [FAQ](#faq)
- [Contact](#contact)
# Overview # Overview
mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures. mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures with enhanced features.
mxisd uses a cascading lookup model which performs lookup from a more authoritative to a less authoritative source, usually doing: It is specifically designed to connect to an Identity store (AD/Samba/LDAP, SQL Database, Web services/application, ...)
- Local identity stores: LDAP, etc. to ease integration of the Matrix ecosystem with an existing infrastructure, or to build a new one using lasting tools.
- Federated identity stores: another Identity Server in charge of a specific domain, if applicable
- Configured identity stores: another Identity Server specifically configured, if part of some sort of group trust
- Root identity store: vector.im/matrix.org central Identity Servers
mxisd provides an alternative to [sydent](https://github.com/matrix-org/sydent), while still connecting to the vector.im and matrix.org Identity servers, mxisd core principle is to map between Matrix IDs and 3PIDs (Thrid-party Identifiers) for the Homeserver and its users.
by implementing the [Matrix Identity Service specification](https://matrix.org/docs/spec/identity_service/unstable.html). 3PIDs can be anything that identify a user, like:
- Email address
- Phone number
- Skype/Live ID
- Twitter handle
- Facebook ID
- ...
mxisd only aims to support workflows that do NOT break federation or basic lookup processes of the Matrix ecosystem. mxisd is an enhanced Identity service, which implements the [Matrix Identity service API](https://matrix.org/docs/spec/identity_service/unstable.html)
but also several other features that greatly enhance user experience within Matrix.
# Features # Features
- Single lookup of 3PID (E-mail, phone number, etc.) by the Matrix Client or Homeserver. As a [regular Matrix Identity service](docs/features/identity.md):
- Bulk lookups when trying to find possible matches within contacts in Android and iOS clients. - Search for people by 3PID using its own Identity stores (LDAP, SQL, etc.)
- Bind of 3PID by a Matrix user within a Matrix client - See [documentation](docs/sessions/3pid.md) - Invite people to rooms by 3PID using its own Identity stores, with [notifications](docs/README.md)
- Support of invitation to rooms by e-mail with e-mail notification to invitee. to the invitee (Email, SMS, etc.)
- Authentication support in [synapse](https://github.com/matrix-org/synapse) via the [REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth). - Allow users to add 3PIDs to their settings/profile
In the pipe: As an enhanced Identity service:
- Support to proxy 3PID bindings in user profile to the central Matrix.org servers - Use a recursive lookup mechanism when searching and inviting people by 3PID, allowing to fetch data from:
- Own Identity store
- Federated Identity servers, if applicable to the 3PID
- Arbitrary Identity servers
- Central Matrix Identity servers
- [Extensive control of where 3PIDs are transmited](docs/sessions/3pid.md), so they are not leaked publicly by users
- [Authentication support](docs/features/authentication.md) for [synapse](https://github.com/matrix-org/synapse) via the
[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth).
- [Directory integration](docs/features/directory-users.md) which allows you to search for users within your
organisation, even without prior Matrix contact.
- [Auto-fill of user profile](docs/features/authentication.md) (Display name, 3PIDs) via the
[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth)
# Lookup Process # Why use mxisd
Default Lookup strategy will use a priority order and a configurable recursive/local type of request. - Use your existing Identity store, do not duplicate information
- Auto-fill user profiles with relevant info
- As an organisation, stay in control of 3PIDs so they are not published to the central Matrix.org servers where they
currently **cannot be removed**
- Users can directly find each other using whatever attribute is relevant within your Identity store
- Federate your Identity lookups so you can discover others and/or others can discover you, all with extensive ACLs
## E-mail # Quick Start
Given the 3PID `john.doe@example.org`, the following will be performed until a mapping is found: 1. [Preparation](#preparation)
- LDAP: lookup the Matrix ID (partial or complete) from a configurable attribute using a dedicated query. 2. [Install](#install)
- DNS: lookup another Identity Server using the domain part of an e-mail and: 3. [Configure](#configure)
- Look for a SRV record under `_matrix-identity._tcp.example.org` 4. [Integrate](#integrate)
- Lookup using the base domain name `example.org` 5. [Validate](#validate)
- Forwarder: Proxy the request to other configurable identity servers.
## Phone number Following these quick start instructions, you will have a basic setup that can perform recursive/federated lookups and
Given the phone number `+123456789`, the following lookup logic will be performed: talk to the central Matrix.org Identity service.
- LDAP: lookup the Matrix ID (partial or complete) from a configurable attribute using a dedicated query. This will be a good ground work for further integration with your existing Identity stores.
- Forwarder: Proxy the request to other configurable identity servers.
# Packages ## Preparation
See [releases]((https://github.com/kamax-io/mxisd/releases)) for native installers of supported systems. You will need:
If none is available, please use other packages or build from source. - Homeserver
- Reverse proxy with regular TLS/SSL certificate (Let's encrypt) for your mxisd domain
## Debian As synapse requires an HTTPS connection when talking to an Identity service, a reverse proxy is required as mxisd does
### Download not support HTTPS listener at this time.
See the [releases section](https://github.com/kamax-io/mxisd/releases).
### Configure and run For maximum integration, it is best to have your Homeserver and mxisd reachable via the same hostname.
After installation: You can also use a dedicated domain for mxisd, but will not have access to some features.
1. Copy the sample config file `/etc/mxisd/mxisd-sample.yaml` to `/etc/mxisd/mxisd.yaml`
2. [Configure](#configuration)
3. Start the service: `sudo systemctl start mxisd`
### From source Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-io/mxisd/wiki/Gotchas#nating) if you use the same
Requirements: hostname.
- fakeroot
- dpkg-deb
Run: The following Quick Start guide assumes you will host the Homeserver and mxisd under the same hostname.
```
./gradlew buildDeb
```
You will find the debian package in `build/dist`
## Docker
```
docker pull kamax/mxisd
```
For more info, see [the public repository](https://hub.docker.com/r/kamax/mxisd/)
### From source
[Build mxisd](#build) then build the docker image:
```
./gradlew dockerBuild
```
You can run a container of the given image and test it with the following command (adapt volumes host paths):
```
docker run -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t kamax/mxisd:latest-dev
```
# From Source
## Requirements
- JDK 1.8
## Build
```
git clone https://github.com/kamax-io/mxisd.git
cd mxisd
./gradlew build
```
then see the [Configuration](#configuration) section.
## Test build
Start the server in foreground to validate the build:
```
java -jar build/libs/mxisd.jar
```
Ensure the signing key is available:
```
$ 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):
```
$ curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=mxisd-lookup-test@kamax.io'
{"address":"mxisd-lookup-test@kamax.io","medium":"email","mxid":"@mxisd-lookup-test:kamax.io",...}
```
If you enabled LDAP, you can also validate your config with a similar request after replacing the `address` value with something present within your LDAP
```
curl "http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=john.doe@example.org"
```
If you plan on testing the integration with a homeserver, you will need to run an HTTPS reverse proxy in front of it
as the reference Home Server implementation [synapse](https://github.com/matrix-org/synapse) requires a HTTPS connection
to an ID server.
See the [Integration section](#integration) for more details.
## Install ## Install
After [building](#build) the software, run all the following commands as `root` or using `sudo` Install via:
1. Prepare files and directories: - [Debian package](docs/install/debian.md)
- [Docker image](docs/install/docker.md)
- [Sources](docs/build.md)
See the [Latest release](https://github.com/kamax-io/mxisd/releases/latest) for links to each.
## Configure
Create/edit a minimal configuration (see installer doc for the location):
``` ```
# Create a dedicated user matrix.domain: 'MyMatrixDomain.org'
useradd -r mxisd key.path: '/path/to/signing.key.file'
storage.provider.sqlite.database: '/path/to/mxisd.db'
```
- `matrix.domain` should be set to your Homeserver domain
- `key.path` will store the signing keys, which must be kept safe!
- `storage.provider.sqlite.database` is the location of the SQLite Database file which will hold state (invites, etc.)
# Create bin directory If your HS/mxisd hostname is not the same as your Matrix domain, configure `server.name`.
mkdir /opt/mxisd Complete configuration guide is available [here](docs/configure.md).
# Create config directory and set ownership ## Integrate
mkdir /etc/mxisd ### Reverse proxy
chown mxisd /etc/mxisd #### Apache2
In the VirtualHost handling the domain with SSL, add the following line, replacing `0.0.0.0` by the right address/host.
# Create data directory and set ownership **This line MUST be present before the one for the homeserver!**
mkdir /var/opt/mxisd ```
chown mxisd /var/opt/mxisd ProxyPass /_matrix/identity http://0.0.0.0:8090/_matrix/identity
# Copy <repo root>/build/libs/mxisd.jar to bin directory
cp ./build/libs/mxisd.jar /opt/mxisd/
chown mxisd /opt/mxisd/mxisd.jar
chmod a+x /opt/mxisd/mxisd.jar
# Create symlink for easy exec
ln -s /opt/mxisd/mxisd.jar /usr/bin/mxisd
``` ```
2. Copy the config file created earlier `./application.example.yaml` to `/etc/mxisd/mxisd.yaml` Typical VirtualHost configuration would be:
3. [Configure](#configuration)
4. Copy `<repo root>/src/systemd/mxisd.service` to `/etc/systemd/system/` and edit if needed
5. Enable service for auto-startup
``` ```
systemctl enable mxisd <VirtualHost *:443>
``` ServerName example.org
6. Start mxisd
``` ...
systemctl start mxisd
ProxyPreserveHost on
ProxyPass /_matrix/identity/ http://10.1.2.3:8090/_matrix/identity/
ProxyPass /_matrix/ http://10.1.2.3:8008/_matrix/
</VirtualHost>
``` ```
# Configuration ### Synapse
After following the specific instructions to create a config file from the sample: Add your mxisd domain into the `homeserver.yaml` at `trusted_third_party_id_servers` and restart synapse.
1. Set the `matrix.domain` value to the domain value used in your Home Server configuration In a typical configuration, you would end up with something similair to:
2. Set an absolute location for the signing keys using `key.path`
3. Configure the E-mail notification sender following [the documentation](docs/threepids/medium/email/smtp-connector.md)
4. If you would like to support Phone number validation, see the [Twilio configuration](docs/threepids/medium/msisdn/twilio-connector.md)
In case your IS public domain does not match your Matrix domain, see `server.name` and `server.publicUrl`
config items.
## Backends
### LDAP (AD, Samba, LDAP)
If you want to use LDAP backend as an Identity store:
1. Enable it with `ldap.enabled`
2. Configure connection options using items starting in `ldap.connection`
3. You may want to valid default values for `ldap.attribute` items
### SQL (SQLite, PostgreSQL)
If you want to connect to use a synapse DB (SQLite or PostgreSQL) as Identity store, follow the example config for `sql` config items.
### REST (Webapps/websites integration)
If you want to use the REST backend as an Identity store:
1. Enable it with `rest.enabled`
2. Configure options starting with `rest` and see the dedicated documentation in `docs/backends/rest.md`
# Network Discovery
To allow other federated Identity Server to reach yours, the same algorithm used for Homeservers takes place:
1. Check for the appropriate DNS SRV record
2. If not found, use the base domain
If your Identity Server public hostname does not match your Matrix domain, configure the following DNS SRV entry
and replace `matrix.example.com` by your Identity server public hostname - **Make sure to end with a final dot!**
``` ```
_matrix-identity._tcp.example.com. 3600 IN SRV 10 0 443 matrix.example.com. trusted_third_party_id_servers:
- matrix.org
- vector.im
- example.org
``` ```
This would only apply for 3PID that are DNS-based, like e-mails. For anything else, like phone numbers, no federation It is recommended to remove `matrix.org` and `vector.im` so only your own Identity server is allowed by synapse.
is currently possible.
The port must be HTTPS capable. Typically, the port `8090` of mxisd should be behind a reverse proxy which does HTTPS. ### Federation and network discovery
See the [integration section](#integration) for more details. See the [dedicated document](docs/features/federation.md).
# Integration ## Validate
- [HTTPS and Reverse proxy](https://github.com/kamax-io/mxisd/wiki/HTTPS) Log in using your Matrix client and set `https://example.org` as your Identity server URL, replacing `example.org` by
- [synapse](https://github.com/kamax-io/mxisd/wiki/Homeserver-Integration) as Identity server the relevant hostname which you configured in your reverse proxy.
- [synapse with REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth/blob/master/README.md)
as authentication module Try to invite `mxisd-lookup-test@kamax.io`, which should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`
If it worked, it means you are up and running and can enjoy mxisd in its basic mode! Congratulations!
You can now integrate mxisd further with your infrastructure using the various [features](docs/README.md) guides.
# Support # Support
## Community ## Community
@@ -225,3 +162,74 @@ For more high-level discussion about the Identity Server architecture/API, go to
## Professional ## Professional
If you would prefer professional support/custom development for mxisd and/or for Matrix in general, including other open source technologies/products, If you would prefer professional support/custom development for mxisd and/or for Matrix in general, including other open source technologies/products,
please visit [our website](https://www.kamax.io/) to get in touch with us and get a quote. please visit [our website](https://www.kamax.io/) to get in touch with us and get a quote.
We offer affordable monthly/yearly support plans for mxisd, synapse or your full Matrix infrastructure.
# FAQ
### Do I need to use mxisd if I run a Homeserver?
No, but it is recommended, even if you don't use any backends or integration.
mxisd in its default configuration will use federation and involve the central Matrix.org Identity servers when
performing queries, giving you access to at least the same information than if you were not running it.
It will also give your users a choice to make their 3PIDs available publicly, ensuring they are made aware of the
privacy consequences, which is not the case with the central Matrix.org servers.
So mxisd is like your gatekeeper and guardian angel. It doesn't change what you already know, just adds some nice
simple features on top of it.
### I saw that sydent is the official Identity server implemenation of the Matrix team, I should use that!
You can, but [sydent](https://github.com/matrix-org/sydent):
- [was never meant to be self-hosted and should not be done](https://github.com/matrix-org/sydent/issues/22)
- is not meant to be linked to a specific Homeserver / domain
- cannot handle federation or proxy lookups, effectively isolating your users from the rest of the network
- forces you to duplicate all your identity data, so people can be found by 3PIDs
- forces users to enter all their emails and phone numbers manually in their profile
So really, you should go with mxisd.
### I'm not sure I understand what an "Identity server" is supposed to be or do
The current Identity service API is more a placeholder, as the Matrix devs did not have time so far to really work on
what they want to do with that part of the ecosystem. Therefore, "Identity" is a missleading word currently.
Given the scope of the current Identity Service API, their would be best called "Directory and Invitation service".
Because the current scope is so limited and no integration is done with the Homeserver, there was a big lack of features
for groups/corporations/organisation. This is where mxisd comes in.
mxisd implements the Identity Service API and also a set of features which are expected by regular users, truely living
up to its "Identity server" name.
### So mxisd is just a big hack! I don't want to use non-official features!
mxisd primary concern is to always be compatible with the Matrix ecosystem and the Identity service API.
Whenever the API will be updated and/or enchanced, mxisd will follow, remaining 100% compatible with the ecosystem.
We also directly talk with the Matrix developers to ensure all features we implement have their approval, and that we
are in line with their vision of Identity management within the Matrix ecosystem.
Therefore, using mxisd is a safe choice. It will be like using the central Matrix.org Identity servers, yet not closing
the door to very nice enhancements and integrations.
### Should I use mxisd if I don't host my own Homeserver?
No
# Contribute
First and foremost, the best way to contribute is to use mxisd and tell us about it!
We would love to hear about your experience and get your feedback on how to make it an awesome product.
You can contribute as a community member by:
- Opening issues for any weird behaviour or bug. mxisd should feel natural, let us know if it doesn't!
- Helping us improve the documentation: tell us what is good or not good (in an issue or in Matrix), or make a PR with
changes you feel improve the doc
- Contribute code directly: we love contributors! We are quite strict in our reviews but and we'll always review your PR
in a timely fashion.
- Donate! any donation is welcome, regardless how small or big. This will directly be used for the fixed costs and
developer time.
You can contribute as an organisation/corporation by:
- Get a [support contract](#support-professional). This is the best way you can help us as it ensures mxisd is maintained regularly and you get
direct access to the support team.
- Sponsoring new features or bug fixes. We'll quote the cost of development, at a reduced rate, and maintain the code
in future release of mxisd. (subject to approval of the feature on our end)
# Contact
Get in touch on Matrix: [#mxisd:kamax.io](https://matrix.to/#/#mxisd:kamax.io)

389
application.example.yaml
View File

@@ -1,11 +1,6 @@
# Sample configuration file explaining all possible options, their default value and if they are required or not. # Sample configuration file explaining the minimum required keys to be set to run mxisd
# #
# Any optional configuration item will be prefixed by # (comment character) with the configuration item following # For a complete list of options, see https://github.com/kamax-io/mxisd
# directly without any whitespace character.
# Default values for optional configuration item will also follow such item.
#
# Any mandatory configuration item will not be prefixed by # and will also contain a value as example that must be
# changed. It is advised to re-create a clean config file with only the required configuration item.
####################### #######################
# Matrix config items # # Matrix config items #
@@ -16,48 +11,9 @@
matrix.domain: '' matrix.domain: ''
################
####################### # Signing keys #
# Server config items # ################
#######################
# Indicate on which port the Identity Server will listen.
#
# This is be default an unencrypted port.
# HTTPS can be configured using Tomcat configuration properties.
#
#server.port: 8090
# Public hostname of this identity server.
#
# This would be typically be the same as your Matrix domain.
# In case it is not, set this value.
#
# This value is used in various signatures within the Matrix protocol and should be a reachable hostname.
# You can validate by ensuring you see a JSON answer when calling (replace the domain):
# https://example.org/_matrix/identity/status
#
#server.name: 'example.org'
# Public URL to reach this identity server
#
# This is used with 3PID invites in room and other Homeserver key verification workflow.
# If left unconfigured, it will be generated from the server name.
#
# You should typically set this value if you want to change the public port under which
# this Identity server is reachable.
#
# %SERVER_NAME% placeholder is available to avoid configuration duplication.
# e.g. 'https://%SERVER_NAME%:8443'
#
#server.publicUrl: 'https://example.org'
#############################
# Signing keys config items #
#############################
# Absolute path for the Identity Server signing key. # Absolute path for the Identity Server signing key.
# During testing, /var/tmp/mxisd.key is a possible value # During testing, /var/tmp/mxisd.key is a possible value
# #
@@ -65,278 +21,7 @@ matrix.domain: ''
# - /var/opt/mxisd/sign.key # - /var/opt/mxisd/sign.key
# - /var/local/mxisd/sign.key # - /var/local/mxisd/sign.key
# - /var/lib/mxisd/sign.key # - /var/lib/mxisd/sign.key
key.path: '/path/to/sign.key' key.path: ''
#################################
# Recurisve lookup config items #
#################################
# Configuration items for recursion-type of lookup
#
# Lookup access are divided into two types:
# - Local
# - Remote
#
# This is similar to DNS lookup and recursion and is therefore prone to the same vulnerabilities.
# By default, only non-public hosts are allowed to perform recursive lookup.
#
# This will also prevent very basic endless loops where host A ask host B, which in turn is configured to ask host A,
# which would then ask host B again, etc.
# Enable recursive lookup globally
#
#lookup.recursive.enabled: true
# Whitelist of CIDR that will trigger a recursive lookup.
# The default list includes all private IPv4 address and the IPv6 loopback.
#
#lookup.recursive.allowedCidr:
# - '127.0.0.0/8'
# - '10.0.0.0/8'
# - '172.16.0.0/12'
# - '192.168.0.0/16'
# - '::1/128'
# In case no binding is found, query an application server which implements the single lookup end-point
# to return bridge virtual user that would allow the user to be contacted directly by the said bridge.
#
# If a binding is returned, the application server is not expected to sign the message as it is not meant to be
# reachable from the outside.
# If a signature is provided, it will be discarded/replaced by this IS implementation (to be implemented).
#
# IMPORTANT: This bypass the regular Invite system of the Homeserver. It will be up to the Application Server
# to handle such invite. Also, if the bridged user were to actually join Matrix later, or if a 3PID binding is found
# room rights and history would not be transferred, as it would appear as a regular Matrix user to the Homeserver.
#
# This configuration is only helpful for Application Services that want to overwrite bridging for 3PID that are
# handled by the Homeserver. Do not enable unless the Application Server specifically supports it!
# Enable unknown 3PID bridging globally
#
#lookup.recursive.bridge.enabled: false
# Enable unknown 3PID bridging for hosts that are allowed to perform recursive lookups.
# Leaving this setting to true is highly recommended in a standard setup, unless this Identity Server
# is meant to always return a virtual user MXID even for the outside world.
#
#lookup.recursive.bridge.recursiveOnly: true
# This mechanism can handle the following scenarios:
#
# - Single Application Server for all 3PID types: only configure the server value, comment out the rest.
#
# - Specific Application Server for some 3PID types, default server for the rest: configure the server value and
# each specific 3PID type.
#
# - Only specific 3PID types: do not configure the server value or leave it empty/blank, configure each specific
# 3PID type.
# Default application server to use for all 3PID types. Remove config item or leave empty/blank to disable.
#
#lookup.recursive.bridge.server: ''
# Configure each 3PID type with a specific application server. Remove config item or leave empty/blank to disable.
#
#lookup.recursive.bridge.mappings.email: 'http://localhost:8091'
#lookup.recursive.bridge.mappings.msisdn: ''
#####################
# LDAP config items #
#####################
# Global enable/disable switch
#
#ldap.enabled: false
#### Connection related config items
# If the connection should be secure
#
#ldap.connection.tls: false
# Host to connect to
#
#ldap.connection.host: 'localhost'
# Port to connect to
#
#ldap.connection.port: 389
# Bind DN for the connection.
#
# If Bind DN and password are empty, anonymous authentication is performed
#
#ldap.connection.bindDn: 'CN=Matrix Identity Server,CN=Users,DC=example,DC=org'
# Bind password for the connection.
#
#ldap.connection.bindPassword: 'password'
# Base DN used in all queries
#
#ldap.connection.baseDn: 'CN=Users,DC=example,DC=org'
#### How to map Matrix attributes with LDAP attributes when performing lookup/auth
#
# How should we resolve the Matrix ID in case of a match using the attribute.
#
# The following type are supported:
# - uid : the attribute only contains the UID part of the Matrix ID. e.g. 'john.doe' in @john.doe:example.org
# - mxid : the attribute contains the full Matrix ID - e.g. '@john.doe:example.org'
#
#ldap.attribute.uid.type: 'uid'
# The attribute containing the binding itself. This value will be used differently depending on the type.
#
# /!\ This should match the synapse LDAP Authenticator 'uid' configuration /!\
#
# Typical values:
# - For type 'uid': 'userPrincipalName' or 'uid' or 'saMAccountName'
# - For type 'mxid', regardless of the directory type, we recommend using 'pager' as it is a standard attribute and
# is typically not used.
#
#ldap.attribute.uid.value: 'userPrincipalName'
# The display name of the user
#
#ldap.attribute.name: 'displayName'
#### Configuration section relating the authentication of users performed via LDAP.
#
# This can be done using the REST Auth module for synapse and pointing it to the identity server.
# See https://github.com/kamax-io/matrix-synapse-rest-auth
#
# During authentication, What to filter potential users by, typically by using a dedicated group.
# If this value is not set, login check will be performed for all entities within the LDAP
#
# Example: (memberOf=CN=Matrix Users,CN=Users,DC=example,DC=org)
#
#ldap.auth.filter: ''
#### Configuration section relating to identity lookups
#
# E-mail query
#
#ldap.identity.medium.email: "(|(mailPrimaryAddress=%3pid)(mail=%3pid)(otherMailbox=%3pid))"
# Phone numbers query
#
# Phone numbers use the MSISDN format: https://en.wikipedia.org/wiki/MSISDN
# This format does not include international prefix (+ or 00) and therefore has to be put in the query.
# Adapt this to your needs for each attribute.
#
#ldap.identity.medium.msisdn: "(|(telephoneNumber=+%3pid)(mobile=+%3pid)(homePhone=+%3pid)(otherTelephone=+%3pid)(otherMobile=+%3pid)(otherHomePhone=+%3pid))"
############################
# SQL Provider config item #
############################
#
# Example configuration to integrate with synapse SQLite DB (default configuration)
#
#sql.enabled: true
#sql.type: 'sqlite'
#sql.connection: '/var/lib/matrix-synapse/homeserver.db'
#
# Example configuration to integrate with synapse PostgreSQL DB
#sql.enabled: true
#sql.type: 'postgresql'
#sql.connection: '//dnsOrIpToServer/dbName?user=synapseDbUser&password=synapseDbPassword'
#
# Configuration for an arbitrary server with arbitrary driver
#
# sql.identity.type possible values:
# - uid Returned value is the localpart of the Matrix ID
# - mxid Full Matrix ID, including domain
#
# sql.identity.query MUST contain a column with label 'uid'
#
# If you would like to overwrite the global lookup query for specific medium type,
# add a config item (see below for example) in the following format
# sql.identity.medium.theMediumIdYouWant: 'the query'
#sql.enabled: true
#sql.type: 'jdbcDriverName'
#sql.connection: '//dnsOrIpToServer/dbName?user=synapseDbUser&password=synapseDbPassword'
#sql.identity.type: 'mxid'
#sql.identity.query: 'SELECT raw AS uid FROM table WHERE medium = ? AND address = ?'
#sql.identity.medium.email: 'SELECT raw AS uid FROM emailTable WHERE address = ?'
#######################################
# Lookup queries forward config items #
#######################################
# List of forwarders to use to try to match a 3PID.
#
# Each server will be tried in the given order, going to the next if no binding was found or an error occurred.
# These are the current root Identity Servers of the Matrix network.
#
#forward.servers:
# - "https://matrix.org"
# - "https://vector.im"
###################################
# 3PID notifications config items #
###################################
# If you would like to change the content, see https://github.com/kamax-io/mxisd/blob/master/docs/threepids/notifications/template-generator.md
#
#### E-mail invite sender
#
# SMTP host
threepid.medium.email.connectors.smtp.host: "smtp.example.org"
# SMTP port
threepid.medium.email.connectors.smtp.port: 587
# TLS mode for the connection.
#
# Possible values:
# 0 Disable TLS entirely
# 1 Enable TLS if supported by server
# 2 Force TLS and fail if not available
#
#threepid.medium.email.connectors.smtp.tls: 1
# Login for SMTP
threepid.medium.email.connectors.smtp.login: "matrix-identity@example.org"
# Password for the account
threepid.medium.email.connectors.smtp.password: "ThePassword"
# The e-mail to send as. If empty, will be the same as login
threepid.medium.email.identity.from: "matrix-identity@example.org"
############################ ############################
@@ -349,10 +34,7 @@ threepid.medium.email.identity.from: "matrix-identity@example.org"
# #
#storage.backend: 'sqlite' #storage.backend: 'sqlite'
# Path to the SQLite DB file
#### Generic SQLite provider config
#
# Path to the SQLite DB file, required if SQLite backend is chosen
# #
# Examples: # Examples:
# - /var/opt/mxisd/mxisd.db # - /var/opt/mxisd/mxisd.db
@@ -362,22 +44,53 @@ threepid.medium.email.identity.from: "matrix-identity@example.org"
storage.provider.sqlite.database: '/path/to/mxisd.db' storage.provider.sqlite.database: '/path/to/mxisd.db'
################
# LDAP Backend #
################
# If you would like to integrate with your AD/Samba/LDAP server,
# see https://github.com/kamax-io/mxisd/blob/master/docs/backends/ldap.md
###################### ###############
# DNS-related config # # SQL Backend #
###################### ###############
# The domain to overwrite # If you would like to integrate with a MySQL/MariaDB/PostgreQL/SQLite DB,
# see https://github.com/kamax-io/mxisd/blob/master/docs/backends/sql.md
################
# REST Backend #
################
# If you would like to integrate with an existing web service/webapp,
# see https://github.com/kamax-io/mxisd/blob/master/docs/backends/rest.md
#################################################
# Notifications for invites/addition to profile #
#################################################
# If you would like to change the content,
# see https://github.com/kamax-io/mxisd/blob/master/docs/threepids/notifications/template-generator.md
# #
#dns.overwrite.homeserver.name: 'example.org' #### E-mail invite sender
# - 'env' from environment variable specified by value
# - any other value will use the value as-is as host
# #
#dns.overwrite.homeserver.type: 'raw' # SMTP host
threepid.medium.email.connectors.smtp.host: "smtp.example.org"
# SMTP port
threepid.medium.email.connectors.smtp.port: 587
# The value to use, depending on the type. # TLS mode for the connection.
# Protocol will always be HTTPS
# #
#dns.overwrite.homeserver.value: 'localhost:8448' # 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
# Login for SMTP
threepid.medium.email.connectors.smtp.login: "matrix-identity@example.org"
# Password for the account
threepid.medium.email.connectors.smtp.password: "ThePassword"
# The e-mail to send as. If empty, will be the same as login
threepid.medium.email.identity.from: "matrix-identity@example.org"

24
docs/README.md Normal file
View File

@@ -0,0 +1,24 @@
# Table of Contents
- Installation
- [Debian package](install/debian.md)
- [Docker](install/docker.md)
- [Build from source](build.md)
- [Configuration](configure.md)
- Features
- [Matrix Identity Service](features/identity.md)
- [Homeserver Authentication](features/authentication.md)
- [Directory seach](features/directory-users.md)
- [Identity server Federation](features/federation.md)
- [Bridge integration](features/bridge-integration.md)
- Backends
- [LDAP](backends/ldap.md)
- [SQL](backends/sql.md)
- [REST](backends/rest.md)
- [Google Firebase](backends/firebase.md)
- Notifications
- Handlers
- [Basic](threepids/notifications/basic-handler.md)
- [SendGrid](threepids/notifications/sendgrid-handler.md)
- [Sessions](sessions/3pid.md)
- [Views](sessions/3pid-views.md)

9
docs/backends/firebase.md Normal file
View File

@@ -0,0 +1,9 @@
# Google Firebase
## Configuration
To be completed. For now, see default structure and values:
```
firebase:
enabled: false
credentials: '/path/to/firebase/credentials.json'
database: 'https://my-project.firebaseio.com/'
```

86
docs/backends/ldap.md Normal file
View File

@@ -0,0 +1,86 @@
# AD/Samba/LDAP backend
## Configuration
### Structure and default values
```
ldap:
enabled: false
filter: ''
connection:
host: ''
tls: false
port: 389
bindDn: ''
bindPassword: ''
baseDn: ''
attribute:
uid:
type: 'uid'
value: 'userPrincipalName'
name: 'displayName'
threepid:
email:
- 'mailPrimaryAddress'
- 'mail'
- 'otherMailbox'
msisdn:
- 'telephoneNumber'
- 'mobile'
- 'homePhone'
- 'otherTelephone'
- 'otherMobile'
- 'otherHomePhone'
auth:
filter: ''
directory:
attribute:
other: []
filter: ''
identity:
filter: ''
medium:
email: ''
msisdn: ''
```
### General
| Item | Description |
|-----------|-------------------------------------------------------------------------------------------|
| `enabled` | Globaly enable/disable the LDAP backend |
| `filter` | Global filter to apply on all LDAP queries. Can be overwritten in each applicable section |
### Connection
| Item | Description |
|----------------|------------------------------------------------------|
| `host` | Host to connect to |
| `port` | Port to use |
| `tls` | boolean to use TLS or not (STARTLS is not supported) |
| `bindDn` | Bind DN for authentication |
| `bindPassword` | Bind password |
| `baseDn` | Base DN for queries |
### Attributes
| Item | Description |
|-------------|------------------------------------------------------------------------------------------------------------------------|
| `uid.type` | Indicate how to process the User ID (UID) attribute: |
| | - `uid` will consider the value as the [Localpart](https://matrix.org/docs/spec/intro.html#user-identifiers) |
| | - `mxid` will consider the value as a complete [Matrix ID](https://matrix.org/docs/spec/intro.html#user-identifiers) |
| `uid.value` | Attribute name refering to the User ID. This is typically `userPrincipalName` on AD/Samba setups and `uid` in LDAP |
| `name` | Attribute name that contains the [Display Name](https://matrix.org/docs/spec/intro.html#profiles) of the user |
| `threepid` | Namespace where each key is a 3PID type and contains a list of attributes |
### Authentication
| Item | Description |
|----------|--------------------------------------------------------------------------------------------------|
| `filter` | Specific user filter applied during authentication. Global filter is used if empty/blank/not set |
### Directory
| Item | Description |
|-------------------|---------------------------------------------------------------------|
| `attribute.other` | Additional attributes to be used when performing directory searches |
| `filter` | Specific user filter applied during directory search. |
| | Global filter is used if empty/blank/not set |
### Identity
| Item | Description |
|----------|---------------------------------------------------------------------------------------------------|
| `filter` | Specific user filter applied during identity search. Global filter is used if empty/blank/not set |
| `medium` | Namespace to overwrite generated queries from the list of attributes for each 3PID medium |

23
docs/backends/sql.md Normal file
View File

@@ -0,0 +1,23 @@
# SQL Backend
## Configuration
To be completed. For now, see default structure and values:
```
sql:
enabled: false
type: 'sqlite' or 'postgresql'
connection: ''
auth:
enabled: false
directory:
enabled: false
query:
name:
type: 'localpart'
value: 'SELECT 1'
threepid:
type: 'localpart'
value: 'SELECT 1'
identity:
type: 'localpart'
query: 'SELECT user_id AS uid FROM user_threepids WHERE medium = ? AND address = ?'
```

105
docs/build.md Normal file
View File

@@ -0,0 +1,105 @@
# From source
- [Binaries](#binaries)
- [Debian package](#debian-package)
- [Docker image](#docker-image)
## Binaires
### Requirements
- JDK 1.8
### Build
```
git clone https://github.com/kamax-io/mxisd.git
cd mxisd
./gradlew build
```
Create a new configuration file by coping `application.example.yaml` to `application.yaml` and edit to your needs.
For advanced configuration, see the [Configure section](configure.md).
Start the server in foreground to validate the build and configuration:
```
java -jar build/libs/mxisd.jar
```
Ensure the signing key is available:
```
$ 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):
```
$ curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=mxisd-lookup-test@kamax.io'
{"address":"mxisd-lookup-test@kamax.io","medium":"email","mxid":"@mxisd-lookup-test:kamax.io",...}
```
If you enabled LDAP, you can also validate your config with a similar request after replacing the `address` value with
something present within your LDAP
```
curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=john.doe@example.org'
```
If you plan on testing the integration with a homeserver, you will need to run an HTTPS reverse proxy in front of it
as the reference Home Server implementation [synapse](https://github.com/matrix-org/synapse) requires a HTTPS connection
to an ID server.
See the [Integration section](#integration) for more details.
### Install
1. Prepare files and directories:
```
# Create a dedicated user
useradd -r mxisd
# Create bin directory
mkdir /opt/mxisd
# Create config directory and set ownership
mkdir /etc/opt/mxisd
chown mxisd /etc/opt/mxisd
# Create data directory and set ownership
mkdir /var/opt/mxisd
chown mxisd /var/opt/mxisd
# Copy <repo root>/build/libs/mxisd.jar to bin directory
cp ./build/libs/mxisd.jar /opt/mxisd/
chown mxisd /opt/mxisd/mxisd.jar
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
4. Copy `<repo root>/src/systemd/mxisd.service` to `/etc/systemd/system/` and edit if needed
5. Enable service for auto-startup
```
systemctl enable mxisd
```
6. Start mxisd
```
systemctl start mxisd
```
## Debian package
### Requirements
- fakeroot
- dpkg-deb
### Build
[Build mxisd](#build) then:
```
./gradlew buildDeb
```
You will find the debian package in `build/dist`
## Docker image
[Build mxisd](#build) then:
```
./gradlew dockerBuild
```
You can run a container of the given image and test it with the following command (adapt volumes host paths):
```
docker run -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t kamax/mxisd:latest-dev
```

183
docs/configure.md Normal file
View File

@@ -0,0 +1,183 @@
# Configuration
- [Syntax](#syntax)
- [Variables](#variables)
- [Categories](#categories)
## Syntax
The configuration file is YAML based, allowing two types of syntax.
Properties-like:
```
my.config.item: 'value'
```
Object-like:
```
my:
config:
item: 'value'
```
These can also be combined within the same file.
Both syntax will be used interchangeably in these documents.
Default values for each possible option are documented [here](../src/main/resources/application.yaml)
## 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`:
```
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.
## Categories
For each category below, the base configuration path will be given, which needs to be appened to every configuration
item described.
Example: if the base path was `basePath` and the following table was given:
| Name | Purpose |
|------|---------|
| item1 | To give an example |
| item2 | To give another example |
The following configurations could be used, all being equivalent:
```
basePath.item1: 'myValue'
basePath.item2: 'myOtherValue'
```
```
basePath:
item1: 'myValue'
item2: 'myOtherValue'
```
```
basePath.item1: 'myValue'
basePath:
item2: 'myOtherValue'
```
---
In case a relative base path is given, it is appended to the one above.
Example: With base path `basePath`, the relative base `relativeBasePath` and the following table:
| Name | Purpose |
|------|---------|
| item1 | To give an example |
| item2 | To give another example |
The following configurations could be used, all being equivalent:
```
basePath.relativeBasePath.item1: 'myValue'
basePath.relativeBasePath.item2: 'myOtherValue'
```
```
basePath:
relativeBasePath:
item1: 'myValue'
item2: 'myOtherValue'
```
```
basePath.relativeBasePath.item1: 'myValue'
basePath:
relativeBasePath:
item2: 'myOtherValue'
```
### Matrix
Base path: `matrix`
| Name | Purpose |
|------|---------|
| `domain` | Matrix domain name, same as the Homeserver, used to build appropriate Matrix IDs |
---
Relative base path: `identity`
| Name | Purpose |
|------|---------|
| `servers` | Namespace to create arbitrary list of Identity servers, usable in other parts of the configuration |
Example:
```
matrix.identity.servers:
root:
- 'https://matrix.org'
```
Create a list under the label `root` containing a single Identity server, `https://matrix.org`
### Server
| Name | Purpose |
|------|---------|
| `name` | Public hostname of mxisd, if different from the Matrix domain |
| `port` | HTTP port to listen on (unencrypted) |
| `publicUrl` | Defaults to `https://${server.name}` |
### Storage
Base path: `storage`
| Name | Purpose |
|------|---------|
| `backend` | Specify which SQL backend to use. only `sqlite` is currently supported. |
---
Relative base path: `provider.sqlite`
| Name | Purpose |
|------|---------|
| `database` | Absolute location of the SQLite database |
### Backends
- [LDAP](backends/ldap.md)
- [SQL](backends/sql.md)
- [REST](backends/rest.md)
- [Google Firebase](backends/firebase.md)
### Lookups
work in progress, should not be configured.
### Sessions
See the [dedicated document](sessions/3pid.md)
### Notifications
Base path: `notification`
| Name | Purpose |
|------|---------|
| handler | Namespace to specify the handler to use for each 3PID |
| handlers | Namespace used by individual handlers for their own configuration |
Example:
```
notification:
handler:
email: 'sendgrid'
msisdn: 'raw'
handlers:
raw:
...
sendgrid:
...
```
- Emails notifications would use the `sendgrid` handler, which define its own configuration user `handlers.sendgrid`
- Phone notification would use the `raw` handler, basic default built-in handler of mxisd
#### Handlers
Relative base path: `handlers`
Built-in:
- [Basic](threepids/notifications/basic-handler.md)
- [SendGrid](threepids/notifications/sendgrid-handler.md)
### Views
See the [dedicated document](sessions/3pid-views.md)
### DNS Overwite
Specific to other features.

7
docs/features/authentication.md Normal file
View File

@@ -0,0 +1,7 @@
# Authentication
Performed via [synapse with REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth/blob/master/README.md)
Point the `endpoint` to mxisd internal IP on port 8090
## Profile auto-fill
To be documented

1
docs/features/bridge-integration.md Normal file
View File

@@ -0,0 +1 @@
To be documented

15
docs/features/directory-users.md
View File

@@ -89,8 +89,7 @@ the `matrix.domain` configuration option and avoid duplicating it.
### Backends ### Backends
#### LDAP #### LDAP
Configuration structure has been altered so queries are automatically built from a global or specific filter and a list To ensure Directory feature works, here's how the LDAP configuration should look like:
of attributes. To ensure Directory feature works, here how the LDAP configuration should look like:
``` ```
ldap: ldap:
enabled: false enabled: false
@@ -123,12 +122,12 @@ ldap:
- 'employeeNumber' - 'employeeNumber'
- 'someOtherAttribute' - 'someOtherAttribute'
``` ```
Previous configuration entries that contained queries with the `%3pid` placeholder should not be used anymore, unless Only include the `attribute` sub-sections if you would like to set another value. Else, it is best not to include them
specifically overwritten. Instead, add all attributes to the relevant sections. to inherit the default values.
If you would like to include an attribute which is not a display name or a 3PID, you can use the If you would like to include an attribute which is not a display name or a 3PID, you can use the
`directory.attribute.other` to list any extra attributes you want included in searches. `directory.attribute.other` to list any extra attributes you want included in searches. If you do not want to include
If you do not want to include any extra attribute, that configuration section can be skipped. any extra attribute, that configuration section can be skipped.
#### SQL #### SQL
If you plan to integrate directory search directly with synapse, use the `synapseSql` provider, based on the following If you plan to integrate directory search directly with synapse, use the `synapseSql` provider, based on the following
@@ -137,9 +136,9 @@ config:
synapseSql: synapseSql:
enabled: true enabled: true
type: <database ID> type: <database ID>
connection: `` connection: '<connection info>'
``` ```
`type` and `connection`, including any other configuration item, follow the same values as the regular `sql` backend. `type` and `connection`, including any other configuration item, follow the same values as the regular [SQL backend](../backends/sql.md).
--- ---

15
docs/features/federation.md Normal file
View File

@@ -0,0 +1,15 @@
# Identity service Federation
To allow other federated Identity Server to reach yours, the same algorithm used for Homeservers takes place:
1. Check for the appropriate DNS SRV record
2. If not found, use the base domain
If your Identity Server public hostname does not match your Matrix domain, configure the following DNS SRV entry
and replace `matrix.example.com` by your Identity server public hostname - **Make sure to end with a final dot!**
```
_matrix-identity._tcp.example.com. 3600 IN SRV 10 0 443 matrix.example.com.
```
This would only apply for 3PID that are DNS-based, like e-mails. For anything else, like phone numbers, no federation
is currently possible.
The port must be HTTPS capable. Typically, TCP port `8090` of mxisd should be behind a reverse proxy which does HTTPS.
See the [main README integration section](../README.md#integration) for more details.

3
docs/features/identity.md Normal file
View File

@@ -0,0 +1,3 @@
To be documented.
Implementation of the [Matrix Identity service API](https://matrix.org/docs/spec/identity_service/unstable.html)

39
docs/install/debian.md Normal file
View File

@@ -0,0 +1,39 @@
# Debian package
## Install
1. Donwload the [latest release](https://github.com/kamax-io/mxisd/releases/latest)
2. Run:
```
dpkg -i /path/to/downloaded/mxisd.deb
```
## Files
| Location | Purpose |
|-----------------------------------|----------------------------------------------|
| /etc/mxisd | Configuration directory |
| /etc/mxisd/mxisd.yaml | Main configuration file |
| /etc/mxisd/signing.key | Default location for mxisd signing keys |
| /etc/systemd/system/mxisd.service | Systemd configuration file for mxisd service |
| /usr/lib/mxisd | Binairies |
| /var/lib/mxisd | Data |
## Control
Start mxisd using:
```
sudo systemctl start mxisd
```
Stop mxisd using:
```
sudo systemctl stop mxisd
```
## Troubleshoot
All logs are sent to `STDOUT` which are saved in `/var/log/syslog` by default.
You can:
- grep & tail using `mxisd`:
```
tail -n 99 -f /var/log/syslog | grep mxisd
```
- use Systemd's journal:
```
journalctl -f n 99 -u mxisd
```

14
docs/install/docker.md Normal file
View File

@@ -0,0 +1,14 @@
# Docker
## Fetch
Pull the latest stable image:
```
docker pull kamax/mxisd
```
## Run
Run it (adapt volume paths to your host):
```
docker run --rm -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t kamax/mxisd
```
For more info, including the list of possible tags, see [the public repository](https://hub.docker.com/r/kamax/mxisd/)

2
docs/sessions/3pid.md
View File

@@ -17,7 +17,7 @@
- [Sessions disabled](#sessions-disabled) - [Sessions disabled](#sessions-disabled)
## Overview ## Overview
When adding an email, a phone number or any other kind of 3PID (Third-Party Identifier), When adding an email, a phone number or any other kind of 3PID (Third-Party Identifier) in a Matrix client,
the identity server is called to validate the 3PID. the identity server is called to validate the 3PID.
Once this 3PID is validated, the Homeserver will publish the user Matrix ID on the Identity Server and Once this 3PID is validated, the Homeserver will publish the user Matrix ID on the Identity Server and

66
docs/threepids/notifications/basic-handler.md Normal file
View File

@@ -0,0 +1,66 @@
# Basic Notification handler
Basic notification handler which uses two components:
- Content generator, to produce the notifications
- Connectors to send the notification content
This handler can be used with the 3PID types:
- `email`
- `msisdn` (Phone numbers)
## Generators
- [Template](template-generator.md)
## Connectors
- Email
- [SMTP](../medium/email/smtp-connector.md)
- SMS
- [Twilio](../medium/msisdn/twilio-connector.md)
## Configuration
Enabled by default or with:
```
notification:
handler:
email: 'raw'
```
**WARNING:** Will be consolidated soon, prone to breaking changes.
Structure and default values:
```
threepid:
medium:
email:
identity:
from: ''
name: ''
connector: 'smtp'
generator: 'template'
connectors:
smtp:
host: ''
port: 587
tls: 1
login: ''
password: ''
generators:
template:
invite: 'classpath:threepids/email/invite-template.eml'
session:
validation:
local: 'classpath:threepids/email/validate-local-template.eml'
remote: 'classpath:threepids/email/validate-remote-template.eml'
msisdn:
connector: 'twilio'
generator: 'template'
connectors:
twilio:
accountSid: ''
authToken: ''
number: ''
generators:
template:
invite: 'classpath:threepids/sms/invite-template.txt'
session:
validation:
local: 'classpath:threepids/sms/validate-local-template.txt'
remote: 'classpath:threepids/sms/validate-remote-template.txt'
```

9
docs/threepids/notifications/sendgrid-handler.md Normal file
View File

@@ -0,0 +1,9 @@
# SendGrid Notification handler
To be completed. See [raw possible configuration items](https://github.com/kamax-io/mxisd/blob/master/src/main/resources/application.yaml#L172).
Enabled with:
```
notification:
handler:
email: 'sendgrid'
```

2
docs/threepids/notifications/template-generator.md
View File

@@ -64,7 +64,7 @@ This template is used when to user which added their 3PID address to their profi
allows remote sessions. allows remote sessions.
**NOTE:** 3PID session always require local validation of a token, even if a remote session is enforced. **NOTE:** 3PID session always require local validation of a token, even if a remote session is enforced.
One cannot bind a MXID to the session until both local and remote sessions have been validated. One cannot bind a Matrix ID to the session until both local and remote sessions have been validated.
#### Placeholders #### Placeholders
| Placeholder | Purpose | | Placeholder | Purpose |

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

@@ -32,7 +32,7 @@ import java.util.Optional;
public class LdapIdentityConfig { public class LdapIdentityConfig {
private String filter; private String filter;
private String token = "%3pid"; private String token;
private Map<String, String> medium = new HashMap<>(); private Map<String, String> medium = new HashMap<>();
public String getFilter() { public String getFilter() {

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

@@ -5,10 +5,10 @@ spring:
logging: logging:
level: level:
org: org:
springframework: "WARN" springframework: 'WARN'
apache: apache:
catalina: "WARN" catalina: 'WARN'
directory: "WARN" directory: 'WARN'
pattern: 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}' 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}'
@@ -16,6 +16,7 @@ server:
port: 8090 port: 8090
matrix: matrix:
domain: ''
identity: identity:
servers: servers:
root: root:
@@ -47,8 +48,12 @@ ldap:
enabled: false enabled: false
filter: '' filter: ''
connection: connection:
host: ''
tls: false tls: false
port: 389 port: 389
bindDn: ''
bindPassword: ''
baseDn: ''
attribute: attribute:
uid: uid:
type: 'uid' type: 'uid'
@@ -74,6 +79,7 @@ ldap:
filter: '' filter: ''
identity: identity:
filter: '' filter: ''
token: '%3pid'
medium: medium:
email: '' email: ''
msisdn: '' msisdn: ''
@@ -81,6 +87,7 @@ ldap:
firebase: firebase:
enabled: false enabled: false
sql: sql:
enabled: false enabled: false
type: 'sqlite' type: 'sqlite'
@@ -106,8 +113,8 @@ synapseSql:
forward: forward:
servers: servers:
- "https://matrix.org" - 'https://matrix.org'
- "https://vector.im" - 'https://vector.im'
threepid: threepid:
medium: medium: