More documentation

docs/backends/README.md

@@ -0,0 +1,5 @@
+# Identity Stores (Backends)
+- [Samba / Active Directory / LDAP](ldap.md)
+- [SQL Databases](sql.md)
+- [Website / Web service / Web app](rest.md)
+- [Google Firebase](firebase.md)

docs/backends/firebase.md

@@ -1,4 +1,14 @@
 # Google Firebase
+https://firebase.google.com/
+
+## Requirements
+This backend requires a suitable Matrix client capable of performing Firebase authentication and passing the following
+information:
+- Firebase User ID as Matrix username
+- Firebase token as Matrix password
+
+If your client is Riot, you will need a custom version.
+
 ## Configuration
 To be completed. For now, see default structure and values:
 ```
@@ -6,4 +16,4 @@ firebase:
   enabled: false
   credentials: '/path/to/firebase/credentials.json'
   database: 'https://my-project.firebaseio.com/'
-```
+```

docs/backends/ldap.md

@@ -1,53 +1,95 @@
-# AD/Samba/LDAP backend
+# LAP (Samba / Active Directory / OpenLDAP)
+## Getting started
+To use your LDAP backend, add the bare minimum configuration in mxisd config file:
+```
+ldap.enabled: true
+ldap.connection.host: 'ldapHostnameOrIp'
+ldap.connection.bindDn: 'CN=My Mxisd User,OU=Users,DC=example,DC=org'
+ldap.connection.bindPassword: 'TheUserPassword'
+ldap.connection.baseDn: 'OU=Users,DC=example,DC=org'
+```
+These are standard LDAP connection configuration. mxisd will try to connect on port default port 389 without encryption.
+
+---
+
+If you would like to use a TLS/SSL connection, use the following configuration options (STARTLS not supported):
+```
+ldap.connection.tls: true
+ldap.connection.port: 12345
+```
+
+---
+
+You can also set a default global filter on any LDAP queries:
+```
+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 Matrux Users`.
+This can be overwritten or append in each specific flow describe below.
+
+---
+
+LDAP features are based on mapping LDAP attributes to Matrix concepts, like a Matrix ID, its localpart, the user display
+name, their email(s) and/or phone number(s).
+     
+Default attributes are well suited for Active Directory/Samba. In case you are using a native LDAP backend, you will
+most certainly configure those mappings.
+
+The following example would set the `uid` attribute as localpart and the Matrix display name to `cn`
+```
+ldap.attribute.uid.type: 'uid'
+ldap.attribute.uid.value: 'uid'
+ldap.attribute.name: 'cn'
+```
+
+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:
+```
+ldap.attribute.threepid.email:
+  - 'mail'
+  - 'otherMailAttribute'
+
+ldap.attribute.threepid.msisdn:
+  - 'phone'
+  - 'otherPhoneAttribute'
+```
+
+## Identity
+Identity features (related to 3PID invites or searches) are enabled and configured using default values and no specific
+configuration item is needed to get started.
+
+If you would like to overwrite some global configuration relative to filter and/or attributes, see the Identity section
+of the Configuration below.
+
+## Authentication
+No further configuration is needed to enable authentication with LDAP once globally enabled and configured.  
+You have the possiblity to use a different query filter if you wish, see Configuration below.
+
+## Directory
+No further configuration is needed to enable directory with LDAP once globally enabled and configured.
+
+If you would like to use extra attributes in search that are not 3PIDs, like nicknames, group names, employee number:
+```
+ldap.directory.attribute.other:
+  - 'myNicknameAttribute'
+  - 'memberOf'
+  - 'employeeNumberAttribute'
+```
+
 ## 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: ''
-```
+Please read the [Configuration](../configure.md) explanatory note if you are not familiar with the terms used below.
+ 
 ### General
+Base path: `ldap`
+
 | 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
+Base path: `ldap.connection`
+
 | Item           | Description                                          |
 |----------------|------------------------------------------------------|
 | `host`         | Host to connect to                                   |
@@ -58,6 +100,8 @@ ldap:
 | `baseDn`       | Base DN for queries                                  |
 
 ### Attributes
+Base path: `ldap.attribute`
+
 | Item        | Description                                                                                                            |
 |-------------|------------------------------------------------------------------------------------------------------------------------|
 | `uid.type`  | Indicate how to process the User ID (UID) attribute:                                                                   |
@@ -68,11 +112,15 @@ ldap:
 | `threepid`  | Namespace where each key is a 3PID type and contains a list of attributes                                              |
 
 ### Authentication
+Base path: `ldap.auth`
+
 | Item     | Description                                                                                      |
 |----------|--------------------------------------------------------------------------------------------------|
 | `filter` | Specific user filter applied during authentication. Global filter is used if empty/blank/not set |
 
 ### Directory
+Base path: `ldap.directory`
+
 | Item              | Description                                                         |
 |-------------------|---------------------------------------------------------------------|
 | `attribute.other` | Additional attributes to be used when performing directory searches |
@@ -80,6 +128,8 @@ ldap:
 |                   | Global filter is used if empty/blank/not set                        |
 
 ### Identity
+Base path: `ldap.identity`
+
 | Item     | Description                                                                                       |
 |----------|---------------------------------------------------------------------------------------------------|
 | `filter` | Specific user filter applied during identity search. Global filter is used if empty/blank/not set |