From 9e8dade2385379f5d8b89f85d6ab09c264d637f0 Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Mon, 18 Sep 2017 10:58:27 +0200 Subject: [PATCH] Clarify README and REST backend doc --- README.md | 15 ++++++++++++--- docs/backends/rest.md | 15 ++++++++++++--- 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index caa6437..1103d77 100644 --- a/README.md +++ b/README.md @@ -171,17 +171,26 @@ systemctl start mxisd After following the specific instructions to create a config file from the sample: 1. Set the `matrix.domain` value to the domain value used in your Home Server configuration 2. Set an absolute location for the signing keys using `key.path` -3. Set a location for the default SQLite persistence using `storage.provider.sqlite.database` -4. Configure the E-mail invite sender with items starting in `invite.sender.email` +3. Configure the E-mail invite sender with items starting in `invite.sender.email` In case your IS public domain does not match your Matrix domain, see `server.name` and `server.publicUrl` config items. -If you want to use the LDAP backend: + +## 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: diff --git a/docs/backends/rest.md b/docs/backends/rest.md index 9ff9c05..094e85a 100644 --- a/docs/backends/rest.md +++ b/docs/backends/rest.md @@ -1,16 +1,25 @@ # REST backend -The REST backend allows you to query arbitrary REST JSON endpoints as backends for the following flows: +The REST backend allows you to query identity data in existing webapps, like: +- Forums (phpBB, Discourse, etc.) +- Custom Identity stores (Keycloak, ...) +- CRMs (Wordpress, ...) +- self-hosted clouds (Nextcloud, ownCloud, ...) + +It supports the following mxisd flows: - Identity lookup - Authentication +To integrate this backend with your webapp, you will need to implement three specific REST endpoints detailed below. + + ## Configuration | Key | Default | Description | ---------------------------------|---------------------------------------|------------------------------------------------------| | rest.enabled | false | Globally enable/disable the REST backend | | rest.host | *empty* | Default base URL to use for the different endpoints. | | rest.endpoints.auth | /_mxisd/identity/api/v1/auth | Endpoint to validate credentials | -| rest.endpoints.identity.single | /_mxisd/identity/api/v1/lookup/single | Endpoint to lookup a single 3PID | -| rest.endpoints.identity.bulk | /_mxisd/identity/api/v1/lookup/bulk | Endpoint to lookup a list of 3PID | +| rest.endpoints.identity.single | /_mxisd/identity/api/v1/lookup/single | Endpoint to query a single 3PID | +| rest.endpoints.identity.bulk | /_mxisd/identity/api/v1/lookup/bulk | Endpoint to query a list of 3PID | Endpoint values can handle two formats: - URL Path starting with `/` that gets happened to the `rest.host`