1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
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)
that offers more fully-featured integration.
Installation
------------
- Included as standard in the deb packages and docker images from matrix.org.
- If you installed into a virtualenv: `pip install matrix-synapse-ldap3`.
- For other installation mechanisms, see the documentation provided by the maintainer.
Usage
-----
Example synapse config:
.. code:: yaml
password_providers:
- module: "ldap_auth_provider.LdapAuthProvider"
config:
enabled: true
uri: "ldap://ldap.example.com:389"
start_tls: true
base: "ou=users,dc=example,dc=com"
attributes:
uid: "cn"
mail: "mail"
name: "givenName"
#bind_dn:
#bind_password:
#filter: "(objectClass=posixAccount)"
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
password_providers:
- module: "ldap_auth_provider.LdapAuthProvider"
config:
enabled: true
uri:
- "ldap://ldap1.example.com:389"
- "ldap://ldap2.example.com:389"
start_tls: true
base: "ou=users,dc=example,dc=com"
attributes:
uid: "cn"
mail: "email"
name: "givenName"
#bind_dn:
#bind_password:
#filter: "(objectClass=posixAccount)"
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
password_providers:
- module: "ldap_auth_provider.LdapAuthProvider"
config:
enabled: true
mode: "search"
uri: "ldap://ldap.example.com:389"
start_tls: true
base: "ou=users,dc=example,dc=com"
attributes:
uid: "cn"
mail: "mail"
name: "givenName"
# Search auth if anonymous search not enabled
bind_dn: "cn=hacker,ou=svcaccts,dc=example,dc=com"
bind_password: "ch33kym0nk3y"
#filter: "(objectClass=posixAccount)"
Active Directory forest support
-------------------------------
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>``
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
password_providers:
- module: "ldap_auth_provider.LdapAuthProvider"
config:
enabled: true
mode: "search"
uri: "ldap://main.example.com:389"
base: "dc=example,dc=com"
# Must be true for this feature to work
active_directory: true
# Optional. Users from this domain may log in without specifying the domain part
default_domain: main.example.com
attributes:
uid: "userPrincipalName"
mail: "mail"
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``.
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.
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
to your Synapse server's logging configuration file:
- Set the value for `handlers.file.level` to `DEBUG`:
.. code:: yaml
handlers:
file:
# [...]
level: DEBUG
- Add the following to the `loggers` section:
.. code:: 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
|
