Add documentation to password_providers config option (matrix-org#7238)

changelog.d/7238.doc

@@ -0,0 +1 @@
+Add documentation to the `password_providers` config option. Add known password provider implementations to docs.

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
 

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

synapse/config/password_auth_providers.py

@@ -35,7 +35,7 @@ def read_config(self, config, **kwargs):
  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 @@ def read_config(self, config, **kwargs):
 
  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