From 29b7e22b939c473649c8619fdfbecec0cee6b029 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Wed, 8 Apr 2020 00:46:50 +0100
Subject: [PATCH] Add documentation to password_providers config option (#7238)

---
 changelog.d/7238.doc                      |  1 +
 docs/password_auth_providers.md           |  5 ++++-
 docs/sample_config.yaml                   | 14 +++++++++++++-
 synapse/config/password_auth_providers.py | 16 ++++++++++++++--
 4 files changed, 32 insertions(+), 4 deletions(-)
 create mode 100644 changelog.d/7238.doc

diff --git a/changelog.d/7238.doc b/changelog.d/7238.doc
new file mode 100644
index 000000000..0e3b4be42
--- /dev/null
+++ b/changelog.d/7238.doc
@@ -0,0 +1 @@
+Add documentation to the `password_providers` config option. Add known password provider implementations to docs.
\ No newline at end of file
diff --git a/docs/password_auth_providers.md b/docs/password_auth_providers.md
index 0db1a3804..96f9841b7 100644
--- a/docs/password_auth_providers.md
+++ b/docs/password_auth_providers.md
@@ -9,7 +9,10 @@ into Synapse, and provides a number of methods by which it can integrate
 with the authentication system.
 
 This document serves as a reference for those looking to implement their
-own password auth providers.
+own password auth providers. Additionally, here is a list of known
+password auth provider module implementations:
+
+* [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3/)
 
 ## Required methods
 
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index be742969c..341781375 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -1657,7 +1657,19 @@ email:
   #template_dir: "res/templates"
 
 
-#password_providers:
+# Password providers allow homeserver administrators to integrate
+# their Synapse installation with existing authentication methods
+# ex. LDAP, external tokens, etc.
+#
+# For more information and known implementations, please see
+# https://github.com/matrix-org/synapse/blob/master/docs/password_auth_providers.md
+#
+# Note: instances wishing to use SAML or CAS authentication should
+# instead use the `saml2_config` or `cas_config` options,
+# respectively.
+#
+password_providers:
+#    # Example config for an LDAP auth provider
 #    - module: "ldap_auth_provider.LdapAuthProvider"
 #      config:
 #        enabled: true
diff --git a/synapse/config/password_auth_providers.py b/synapse/config/password_auth_providers.py
index 9746bbc68..4fda8ae98 100644
--- a/synapse/config/password_auth_providers.py
+++ b/synapse/config/password_auth_providers.py
@@ -35,7 +35,7 @@ class PasswordAuthProviderConfig(Config):
         if ldap_config.get("enabled", False):
             providers.append({"module": LDAP_PROVIDER, "config": ldap_config})
 
-        providers.extend(config.get("password_providers", []))
+        providers.extend(config.get("password_providers") or [])
         for provider in providers:
             mod_name = provider["module"]
 
@@ -52,7 +52,19 @@ class PasswordAuthProviderConfig(Config):
 
     def generate_config_section(self, **kwargs):
         return """\
-        #password_providers:
+        # Password providers allow homeserver administrators to integrate
+        # their Synapse installation with existing authentication methods
+        # ex. LDAP, external tokens, etc.
+        #
+        # For more information and known implementations, please see
+        # https://github.com/matrix-org/synapse/blob/master/docs/password_auth_providers.md
+        #
+        # Note: instances wishing to use SAML or CAS authentication should
+        # instead use the `saml2_config` or `cas_config` options,
+        # respectively.
+        #
+        password_providers:
+        #    # Example config for an LDAP auth provider
         #    - module: "ldap_auth_provider.LdapAuthProvider"
         #      config:
         #        enabled: true