matrix-org · anoadragon453 · Apr 7, 2020 · Apr 7, 2020 · Apr 7, 2020 · Apr 7, 2020
@@ -0,0 +1 @@
+Add documentation to the `password_providers` config option. Add known password provider implementations to docs.
@@ -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
 

@@ -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
 ## Opentracing ## 
 # These settings enable opentracing, which implements distributed tracing. 
 # This allows you to observe the causal chains of events across servers 
 # including requests, key lookups etc., across any server running 
 # synapse or any other other services which supports opentracing 
 # (specifically those implemented with Jaeger). 
 # 
 opentracing: 
     # tracing is disabled by default. Uncomment the following line to enable it. 
     # 
     #enabled: true 
     # The list of homeservers we wish to send and receive span contexts and span baggage. 
     # See docs/opentracing.rst 
     # This is a list of regexes which are matched against the server_name of the 
     # homeserver. 
     # 
     # By defult, it is empty, so no servers are matched. 
     # 
     #homeserver_whitelist: 
     #  - ".*" 
     # Jaeger can be configured to sample traces at different rates. 
     # All configuration options provided by Jaeger can be set here. 
     # Jaeger's configuration mostly related to trace sampling which 
     # is documented here: 
     # https://www.jaegertracing.io/docs/1.13/sampling/. 
     # 
     #jaeger_config: 
     #  sampler: 
     #    type: const 
     #    param: 1 
     #  Logging whether spans were started and reported 
     # 
     #  logging: 
     #    false 
 ## Opentracing ## 
  
 # These settings enable opentracing, which implements distributed tracing. 
 # This allows you to observe the causal chains of events across servers 
 # including requests, key lookups etc., across any server running 
 # synapse or any other other services which supports opentracing 
 # (specifically those implemented with Jaeger). 
 # 
 opentracing: 
     # tracing is disabled by default. Uncomment the following line to enable it. 
     # 
     #enabled: true 
  
     # The list of homeservers we wish to send and receive span contexts and span baggage. 
     # See docs/opentracing.rst 
     # This is a list of regexes which are matched against the server_name of the 
     # homeserver. 
     # 
     # By defult, it is empty, so no servers are matched. 
     # 
     #homeserver_whitelist: 
     #  - ".*" 
  
     # Jaeger can be configured to sample traces at different rates. 
     # All configuration options provided by Jaeger can be set here. 
     # Jaeger's configuration mostly related to trace sampling which 
     # is documented here: 
     # https://www.jaegertracing.io/docs/1.13/sampling/. 
     # 
     #jaeger_config: 
     #  sampler: 
     #    type: const 
     #    param: 1 
  
     #  Logging whether spans were started and reported 
     # 
     #  logging: 
     #    false 
 #    - module: "ldap_auth_provider.LdapAuthProvider"
 #      config:
 #        enabled: true

@@ -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