Migrate README to markdown

README.rst → README.md

@@ -1,28 +1,37 @@
-Synapse LDAP Auth Provider
-==========================
+# Synapse LDAP Auth Provider
 
 Allows synapse to use LDAP as a password provider.
 
 This allows users to log in to synapse with their username and password from an
-LDAP server. There is also `ma1sd <https://github.com/ma1uta/ma1sd>`_ (3rd party)
+LDAP server. There is also [ma1sd](https://github.com/ma1uta/ma1sd) (3rd party)
 that offers more fully-featured integration.
 
-Installation
-------------
-- Included as standard in the `deb packages <https://matrix-org.github.io/synapse/latest/setup/installation.html#matrixorg-packages>`_ and
-  `docker images <https://matrix-org.github.io/synapse/latest/setup/installation.html#docker-images-and-ansible-playbooks>`_ from matrix.org.
+> [!WARNING]
+> Synapse's password provider plugin functionality (which this module relies on)
+> is not compatible with [Matrix Authentication
+> Service](https://github.com/element-hq/matrix-authentication-service) (MAS), the
+> next-gen Matrix auth server.
+>
+> To use Synapse and MAS together with an LDAP backend, it is recommended to use
+> [Dex](https://github.com/dexidp/dex) with [MAS](https://github.com/element-hq/matrix-authentication-service), instead of
+> `matrix-synapse-ldap3`. See [the relevant MAS
+> documentation](https://element-hq.github.io/matrix-authentication-service/setup/migration.html#map-any-upstream-sso-providers)
+> for information on configuring Dex in MAS.
+
+## Installation
+
+- Included as standard in the [deb packages](https://matrix-org.github.io/synapse/latest/setup/installation.html#matrixorg-packages) and
+  [docker images](https://matrix-org.github.io/synapse/latest/setup/installation.html#docker-images-and-ansible-playbooks) from matrix.org.
 - If you installed into a virtualenv:
     - Ensure pip is up-to-date: `pip install -U pip`.
     - Install the LDAP password provider: `pip install matrix-synapse-ldap3`.
 - For other installation mechanisms, see the documentation provided by the maintainer.
 
-Usage
------
+## Usage
 
 Example Synapse configuration:
 
-.. code:: yaml
-
+```yaml
    modules:
     - module: "ldap_auth_provider.LdapAuthProviderModule"
       config:
@@ -43,12 +52,12 @@ Example Synapse configuration:
         #  local_certificate_file: foo.crt
         #  local_private_key_file: bar.pem
         #  local_private_key_password: secret
+```
 
 If you would like to specify more than one LDAP server for HA, you can provide uri parameter with a list.
 Default HA strategy of ldap3.ServerPool is employed, so first available server is used.
 
-.. code:: yaml
-
+```yaml
    modules:
     - module: "ldap_auth_provider.LdapAuthProviderModule"
       config:
@@ -70,13 +79,13 @@ Default HA strategy of ldap3.ServerPool is employed, so first available server i
         #  local_certificate_file: foo.crt
         #  local_private_key_file: bar.pem
         #  local_private_key_password: secret
+```
 
 If you would like to enable login/registration via email, or givenName/email
 binding upon registration, you need to enable search mode. An example config
 in search mode is provided below:
 
-.. code:: yaml
-
+```yaml
    modules:
     - module: "ldap_auth_provider.LdapAuthProviderModule"
       config:
@@ -98,39 +107,38 @@ in search mode is provided below:
         #  local_certificate_file: foo.crt
         #  local_private_key_file: bar.pem
         #  local_private_key_password: secret
+```
 
-Alternatively you can also put the ``bind_password`` of your service user into its
+Alternatively you can also put the `bind_password` of your service user into its
 own file to not leak secrets into your configuration:
 
-.. code:: yaml
-
+```yaml
    modules:
     - module: "ldap_auth_provider.LdapAuthProviderModule"
       config:
         enabled: true
         # all the other options you need
         bind_password_file: "/var/secrets/synapse-ldap-bind-password"
+```
 
-Please note that every trailing ``\n`` in the password file will be stripped automatically.
+Please note that every trailing `\n` in the password file will be stripped automatically.
 
-Active Directory forest support
--------------------------------
+## Active Directory forest support
 
-If the ``active_directory`` flag is set to ``true``, an Active Directory forest will be
+If the ``active_directory`` flag is set to `true`, an Active Directory forest will be
 searched for the login details.
 In this mode, the user enters their login details in one of the forms:
 
-- ``<login>/<domain>``
-- ``<domain>\<login>``
+- `<login>/<domain>`
+- `<domain>\<login>`
 
-In either case, this will be mapped to the Matrix UID ``<login>/<domain>`` (The 
-normal AD domain separators, ``@`` and ``\``, cannot be used in Matrix User Identifiers, so 
-``/`` is used instead.)
+In either case, this will be mapped to the Matrix UID `<login>/<domain>` (The 
+normal AD domain separators, `@` and `\`, cannot be used in Matrix User Identifiers, so 
+`/` is used instead.)
 
-Let's say you have several domains in the ``example.com`` forest:
-
-.. code:: yaml
+Let's say you have several domains in the `example.com` forest:
 
+```yaml
    modules:
     - module: "ldap_auth_provider.LdapAuthProviderModule"
       config:
@@ -148,46 +156,46 @@ Let's say you have several domains in the ``example.com`` forest:
            name: "givenName"
         bind_dn: "cn=hacker,ou=svcaccts,dc=example,dc=com"
         bind_password: "ch33kym0nk3y"
+```
 
-With this configuration the user can log in with either ``main\someuser``,
-``main.example.com\someuser``, ``someuser/main.example.com`` or ``someuser``.
+With this configuration the user can log in with either `main\someuser`,
+`main.example.com\someuser`, `someuser/main.example.com` or `someuser`.
 
-Users of other domains in the ``example.com`` forest can log in with ``domain\login``
-or ``login/domain``.
+Users of other domains in the `example.com` forest can log in with `domain\login`
+or `login/domain`.
 
-Please note that ``userPrincipalName`` or a similar-looking LDAP attribute in the format
-``login@domain`` must be used when the ``active_directory`` option is enabled.
+Please note that `userPrincipalName` or a similar-looking LDAP attribute in the format
+`login@domain` must be used when the `active_directory` option is enabled.
 
-Troubleshooting and Debugging
------------------------------
+## Troubleshooting and Debugging
 
-``matrix-synapse-ldap3`` logging is included in the Synapse homeserver log
-(typically ``homeserver.log``). The LDAP plugin log level can be increased to
-``DEBUG`` for troubleshooting and debugging by making the following modifications
+`matrix-synapse-ldap3` logging is included in the Synapse homeserver log
+(typically `homeserver.log`). The LDAP plugin log level can be increased to
+`DEBUG` for troubleshooting and debugging by making the following modifications
 to your Synapse server's logging configuration file:
 
 - Set the value for `handlers.file.level` to `DEBUG`:
 
-.. code:: yaml
-
+```yaml
    handlers:
      file:
        # [...]
        level: DEBUG
+```
 
 - Add the following to the `loggers` section:
 
-.. code:: yaml
-
+```yaml
    loggers:
       # [...]
       ldap3:
         level: DEBUG
       ldap_auth_provider:
         level: DEBUG
+```
 
 Finally, restart your Synapse server for the changes to take effect:
 
-.. code:: sh
-
-   synctl restart
+```shell
+synctl restart
+```