From 57253e236244d31bd27978ce609faec6917c5962 Mon Sep 17 00:00:00 2001
From: Hans van Zijst <hans@procolix.com>
Date: Thu, 14 Nov 2024 16:51:12 +0100
Subject: [PATCH] Added a bit about authentication.

---
 matrix/synapse/README.md | 59 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/matrix/synapse/README.md b/matrix/synapse/README.md
index e8d82fb..a20f3a9 100644
--- a/matrix/synapse/README.md
+++ b/matrix/synapse/README.md
@@ -301,3 +301,62 @@ forgotten_room_retention_period: 7d
 ```
 
 
+# Signon
+
+Logging in can be done in basically two ways: an internal or external
+database. Let's start with the first: users and their passwords are stored in
+Synapse's database.
+
+We use `conf.d/signon.yaml` to configure this stuff.
+
+```
+password_config:
+  policy:
+    enabled: true
+    localdb_enabled: true
+    pepper: CxDC6jU5FAxAcvD
+    minimum_length: 8
+    require_digit: true
+    require_symbol: true
+    require_lowercase: true
+    require_uppercase: true
+```
+
+With this bit, we configure Synapse to let users pick and change their own
+passwords, as long as they meet the configured conditions. Mind you: `pepper` is
+a secret random string that should *NEVER* be changed after initial setup. 
+
+But in a bigger environment you'll probably want to use some authentication
+backend, such as LDAP. LDAP is configured by means of a module (see
+[Synapse LDAP auth Provider](https://github.com/matrix-org/matrix-synapse-ldap3/)
+on Github).
+
+Configuring Synapse to use LDAP, would be something like this:
+
+```
+password_config:
+  policy:
+    enabled: only_for_reauth
+    localdb_enabled: false
+
+password_providers:
+  - module: "ldap_auth_provider.LdapAuthProvider"
+    config:
+      enabled: true
+      uri: "ldap://ldap.example.com:389"
+      start_tls: true
+      base: "ou=users,o=Example,dc=example,dc=com"
+      attributes:
+         uid: "uid"
+         mail: "email"
+         name: "givenName"
+      filter: "(&(objectClass=posixAccount)(accountStatus=active))"
+```
+
+This would connect to ldap.example.com over TLS, and authenticate users that
+live under `ou=users,o=Example,dc=example,dc=com` and that are active Posix
+accounts. Users will not be able to change their passwords via Matrix, they
+have to do that in LDAP.
+
+(this setup has not been tested, although it borrows heavily from the current
+ProcoliX setup).