forked from ome/omero-documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
server-ldap.txt
306 lines (214 loc) · 10.9 KB
/
server-ldap.txt
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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
LDAP authentication
===================
`LDAP <http://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol>`_
is an open standard for querying and modifying directory services that
is commonly used for authentication, authorization and accounting (AAA).
OMERO.server supports the use of an LDAP server to query (but not
modify) AAA information for the purposes of automatic user creation.
This allows OMERO users to be automatically created and placed in groups
according to your existing institution policies. This can significantly
simplify your user administration burden.
The OMERO.server LDAP implementation can handle a number of use cases.
For example:
- Allow every "inetOrgPerson" under ``omero.ldap.base`` to login
- but restrict access based upon an arbitrary LDAP filter, e.g.
::
omero.ldap.user_filter=(memberOf=cn=someGoup,ou=Lab,o=College)
- and add that user to some number of groups, e.g.
::
omero.ldap.new_user_group=:query:(member=@{dn})
How it works
------------
On login, the username provided is searched for in OMERO. If the name
does not exist, then the LDAP plugin is queried for a username matching
the system-wide user filter. If such an LDAP entry exists and the
password matches, a new user with the given username is created, and the
user is added to any groups which match the ``new_user_group`` setting.
On subsequent logins, the user filter and the password are again checked
against the LDAP server, and if there is no longer a match, login is refused.
If you would prefer to only have the ``user_filter`` applied during user
creation and not on every login, see :ref:`legacy_password_providers`.
LDAP properties
---------------
The LDAP plugin is configured via several configuration properties, all
starting with ``omero.ldap.``. The default values for these properties are
set in the file :file:`etc/omero.properties`. An overview of all the
properties is outlined in :ref:`ldap_configuration_overview`.
Minimum configuration
^^^^^^^^^^^^^^^^^^^^^
The following properties are the minimum requirements for logging in to OMERO
using LDAP.
::
omero.ldap.config=true
omero.ldap.urls=ldap://localhost:389
omero.ldap.username=
omero.ldap.password=
omero.ldap.base=ou=example,o=com
After having configured your connection, you can turn LDAP on and off
between restarts by setting ``omero.ldap.config`` to false. The ``base``
property determines where in the LDAP tree searches will begin. No users or
groups will be found if they are not under the base provided.
User lookup
^^^^^^^^^^^
Two user properties are used to look up users by login name and,
if necessary, create new users based on the information in LDAP.
::
omero.ldap.user_filter=(objectClass=person)
omero.ldap.user_mapping=omeName=cn,firstName=givenName,lastName=sn,email=mail
``omero.ldap.user_filter`` will be AND'ed to the username query, and can
contain any valid LDAP filter string. The username query is taken from
the LDAP attribute which gets mapped to "omeName" by
``omero.ldap.user_mapping``. Here, the "cn" is mapped to "omeName", so the
username query is ``(cn=[login name])``. The final query is
``(&(objectClass=person)(cn=[login name]))``, which must return a single
result to be considered valid.
Group lookup
^^^^^^^^^^^^
Three group properties are all concerned with what groups a user
will be placed in on creation.
::
omero.ldap.group_filter=(objectClass=groupOfNames)
omero.ldap.group_mapping=name=cn
omero.ldap.new_user_group=default
The group filter and group mapping work
just as the user filter and mapping do, in that the group name query
will be AND'd with the ``group_filter``. In this case, the final query
would be ``(&(objectClass=groupOfNames)(cn=[group name]))``. However,
these properties may not be used depending on
the value of ``new_user_group``, which can have several different values:
- If not prefixed at all, then the value is simply the name of a group which
all users from LDAP should be added to.
- If prefixed with ``:ou:``, then a user's last organizational unit (OU) will
be used as his or her group. For example, the user with the DN
"cn=frank,ou=TheLab,ou=LifeSciences,o=TheCollege" will be placed in the
group "TheLab".
- If prefixed with ``:attribute:``, then the rest of the string is taken to be
an attribute all of whose values will be taken as group names. For example,
``omero.ldap.new_user_group=:attribute:memberOf`` would add a user to all
the groups named by memberOf. You can prefix this value with ``filtered_``
to have the ``group_filter`` applied to the attribute values, i.e.
``:filtered_attribute:memberOf`` will mean that only the values of memberOf
which match ``group_filter`` will be considered.
- If prefixed with ``:dn_attribute:``, then the rest of the string is taken to
be an attribute all of whose values will be taken as group distinguished
names. For example, ``omero.ldap.new_user_group=:dn_attribute:memberOf``
would add a user to all the groups named by memberOf, where the name of the
group is mapped via ``group_mapping``. You can prefix this value with
``filtered_`` to have the ``group_filter`` applied to the attribute values,
i.e. ``:filtered_dn_attribute:memberOf`` will mean that only the values of
memberOf which match ``group_filter`` will be considered.
- If prefixed with ``:query:``, then the rest of the value is taken as a query
to be AND'ed to the group filter. In the query, values from the user such as
"@{cn}", "@{email}", or "@{dn}" can be used as place holders.
- If prefixed with ``:bean:``, then the rest of the string is the name of a
Spring bean which implements the NewUserGroupBean interface. See the
developer documentation :doc:`/developers/Server/Ldap` for more info.
Compound Filters
^^^^^^^^^^^^^^^^
Both the ``user_filter`` and the ``group_filter`` can contain any valid LDAP
filter string. These must be a valid filter in themselves. e.g.
::
omero.ldap.group_filter=(&(objectClass=groupOfNames)(mail=omero.flag))
This filter is valid and will cause the filter to only match groups that have
the ``mail`` attribute set to the value ``omero.flag``. When combined with
the ``group_mapping``, the final query would be
``(&(&(objectClass=groupOfNames)(mail=omero.flag))(cn=[group name]))``
This is the same as the query
``(&(objectClass=groupOfNames)(mail=omero.flag)(cn=[group name]))`` but setting
``group_filter`` to ``(objectClass=groupOfNames)(mail=omero.flag)`` is not valid
as that is not a valid filter on its own.
To restrict the list of groups to just the ones returned by the above query, the
following setting is also required to remove unmatched groups:
::
omero.ldap.new_user_group=:filtered_dn_attribute:memberOf
.. _ldap_configuration_overview:
LDAP configuration overview
---------------------------
Like many pieces of OMERO.server configuration, LDAP-specific configuration is
done by specifying extra properties during installation. The default values
for the LDAP properties are listed in the :file:`etc/omero.properties` file
inside your OMERO installation directory.
.. note::
Please remember that once a change has been made, a server restart will be
needed.
Change any settings that are necessary via bin/omero config.
- Enable or disable LDAP (true/false)
::
bin/omero config set omero.ldap.config true
- LDAP server URL string
::
bin/omero config set omero.ldap.urls ldap://ldap.example.com:389
.. note::
A |SSL| URL above should look like this:
ldaps://ldap.example.com:636
- LDAP server bind DN (if required; can be empty)
::
bin/omero config set omero.ldap.username cn=Manager,dc=example,dc=com
- LDAP server bind password (if required; can be empty)
::
bin/omero config set omero.ldap.password secret
- LDAP server base search DN
::
bin/omero config set omero.ldap.base dc=example,dc=com
- The filter applied to all users; can be empty in which case any LDAP
user is valid
::
bin/omero config set omero.ldap.user_filter '(objectClass=inetOrgPerson)'
- LDAP referral options (defaults to "ignore"; available options are
"ignore, "follow" or "throw" as per the `JNDI referrals
documentation <http://docs.oracle.com/javase/jndi/tutorial/ldap/referral/jndi.html>`_)
::
bin/omero config set omero.ldap.referral follow
LDAP over |SSL|
---------------
If you are connecting to your server over |SSL|,
that is, if your URL is of the form ``ldaps://ldap.example.com:636`` you will
need to configure a key and trust store for Java. See the
:doc:`server-security` page for more information.
Synchronizing LDAP on user login
--------------------------------
This feature allows for LDAP to be considered the authority on user/group
membership. With the following settings enabled each time a user logs in to
OMERO their LDAP groups will be read from the LDAP server and reflected in
OMERO. Enabling this will result in any bespoke OMERO groups that have been
created being removed from the user's profile. The groups will still exist on
the server but the association between user and group will not be reflected
unless such a link is made in LDAP.
::
bin/omero config set omero.ldap.sync_on_login true
.. _legacy_password_providers:
Legacy password providers
-------------------------
The primary component of the LDAP plugin is the LdapPasswordProvider, which is
responsible for creating users, checking their passwords, and adding them to
or removing them from groups. The default password provider is the
``chainedPasswordProvider`` which first checks LDAP if LDAP is enabled, and
then checks JDBC. This can explicitly be enabled by executing the system admin
command:
::
bin/omero config set omero.security.password_provider chainedPasswordProvider
When the LDAP password provider implementation changes, previous versions can
be configured as necessary.
chainedPasswordProviderNoSalt
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``chainedPasswordProviderNoSalt`` uses the version of the JDBC password
provider without password salting support as available in the OMERO 4.4.x
series. To enable it, use::
bin/omero config set omero.security.password_provider chainedPasswordProviderNoSalt
chainedPasswordProvider431
^^^^^^^^^^^^^^^^^^^^^^^^^^
With the 431 password provider, the user filter is only checked on first login
and not kept on subsequent logins. This allows for an OMERO admin to change
the username of a user in omero to be different than the one kept in LDAP. To
enable it, use:
::
bin/omero config set omero.security.password_provider chainedPasswordProvider431
.. seealso::
:doc:`unix/server-installation`
Installation guide for OMERO.server under UNIX-based platforms
:doc:`server-security`
Security pages for OMERO.server
:doc:`/developers/Server/Ldap`
Developer documentation on extending the LDAP plugin yourself.
:forum:`What are your LDAP requirements? <viewtopic.php?f=5&t=14>`
Forum discussion if you have LDAP requirements that are not covered by the above configuration