1AUTH.CONF(5)                     sympa 6.2.72                     AUTH.CONF(5)
2
3
4

NAME

6       auth.conf - Configuration of authentication mechanisms for web
7       interface of Sympa
8

DESCRIPTION

10       The auth.conf configuration file defines authentication mechanisms for
11       web interface of Sympa.
12
13   auth.conf structure
14       Each paragraph starts with one of the names "user_table", "ldap",
15       "generic_sso", "cas" or "cgi".
16
17       The auth.conf file contains directives in the following format:
18
19         name
20         keyword value
21         keyword value
22         ...
23
24         name
25         keyword value
26         keyword value
27         ...
28
29       Comments start with the "#" character at the beginning of a line.
30
31       Empty lines are also considered as comments and are ignored at the
32       beginning.  After the first paragraph, they are considered as paragraph
33       separators. There should only be one directive per line, but their
34       order in the paragraph is of no importance.
35
36       Succeeding subsections describe available parameters in each paragraph.
37
38   "user_table" paragraph
39       This paragraph is related to Sympa internal authentication by email and
40       password.  Information of users are stored in "user_table" database
41       table.  This is the simplest one.
42
43       "regexp" regexp
44       "negative_regexp"
45           Perl regular expressions applied on an email address provided, to
46           select or block this authentication mechanism for a subset of email
47           addresses.
48
49   "ldap" paragraph
50       This paragraph allows one to login to Sympa using data taken from an
51       LDAP directory. Login is done in two steps:
52
53       •   User provide a user ID or an email address, with a password. These
54           are used to retrieve their distinguished name (DN) in the LDAP
55           directory.
56
57       •   The email attribute is extracted from the directory entry
58           corresponding to the found DN.
59
60       Here is how to configure the LDAP authentication:
61
62       "regexp"
63       "negative_regexp"
64           Same as in the "user_table" paragraph: If an email address is
65           provided (this does not apply to the user ID), then the regular
66           expression will be applied to find out if the LDAP directory can be
67           used to authenticate a subset of users.
68
69       "host"
70           This keyword is mandatory. It is the domain name used in order to
71           bind to the directory and then to extract information. You must
72           mention the port number after the server name. Server replication
73           is supported by listing several servers separated by commas (",").
74
75           Example:
76
77             host ldap.univ-rennes1.fr:389
78
79             host ldap0.university.com:389,ldap1.university.com:389,ldap2.university.com:389
80
81       "timeout"
82           It corresponds to the time limit in the search operation. A
83           "timelimit" that restricts the maximum time (in seconds) allowed
84           for a search. A value of 0 (the default) means that no time limit
85           will be requested.
86
87       "suffix"
88           The root of the DIT (directory information tree). The DN that is
89           the base object entry relative to which the search is to be
90           performed.
91
92           Example:
93
94             dc=university,dc=fr
95
96       "bind_dn"
97           If anonymous bind is not allowed on the LDAP server, a DN and
98           password can be used.
99
100       "bind_password"
101           This password is used, combined with the "bind_dn" above.
102
103       "get_dn_by_uid_filter"
104           Defines the search filter corresponding to the "ldap_uid". (RFC
105           2254 compliant). If you want to apply the filter on the user, use
106           the variable "[sender]". It will work with every type of
107           authentication (user ID, "alternate_email", ...).
108
109           Example:
110
111             (Login = [sender])
112
113             (|(ID = [sender])(UID = [sender]))
114
115       "get_dn_by_email_filter"
116           Defines the search filter corresponding to the email addresses
117           (canonic and alternative --- this is RFC 2254 compliant). If you
118           want to apply the filter on the user, use the variable "[sender]".
119           It will work with every type of authentication (user ID,
120           "alternate_email"..).
121
122           Example: a person is described by
123
124             dn: cn=Fabrice Rafart, ou=Siege, o=MaSociete, c=FR
125             objectClass: person
126             cn: Fabrice Rafart
127             title: Network Responsible
128             o: Siege
129             ou: Data processing
130             telephoneNumber: 01-00-00-00-00
131             facsimileTelephoneNumber: 01-00-00-00-00
132             l: Paris
133             country: France
134             uid: frafart
135             mail: Fabrice.Rafart@MaSociete.fr
136             alternate_email: frafart@MaSociete.fr
137             alternate: rafart@MaSociete.fr
138
139           The filters can be:
140
141             (mail = [sender])
142
143             (| (mail = [sender])(alternate_email = [sender]) )
144
145             (| (mail = [sender])(alternate_email = [sender])(alternate  = [sender]) )
146
147       "email_attribute"
148           The name of the attribute for the canonic email in your directory:
149           for instance "mail", "canonic_email", "canonic_address", ... In the
150           previous example, the canonic email is "mail".
151
152       "alternative_email_attribute"
153           Obsoleted.
154
155           On Sympa 6.2.38 or earlier, web interface provided a cookie named
156           "sympa_altemails" which contained attribute values specified by
157           this parameter along with authenticated email address.  This
158           feature was deprecated.
159
160       "scope"
161           Default value: "sub"
162
163           By default, the search is performed on the whole tree below the
164           specified base object. This may be changed by specifying a scope:
165
166           "base"
167               Search only the base object,
168
169           "one"
170               Search the entries immediately below the base object,
171
172           "sub"
173               Search the whole tree below the base object. This is the
174               default.
175
176       "authentication_info_url"
177           Defines the URL of a document describing LDAP password management.
178           When hitting Sympa's "Send me a password" button, LDAP users will
179           be redirected to this URL.
180
181       TLS parameters
182
183       Following parameters are used to provide LDAPS (LDAP over TLS/SSL):
184
185       "use_ssl" (OBSOLETE)
186           If set to 1, connection to the LDAP server will use LDAPS (LDAP
187           over TLS/SSL).
188
189           Obsoleted as of Sympa 6.2.15. Use "use_tls" instead.
190
191       "use_tls"
192           Default value: "none"
193
194           "ldaps"
195               Use LDAPS (LDAP over TLS/SSL),
196
197           "starttls"
198               Use StartTLS,
199
200           "none"
201               TLS (SSL) is disabled.
202
203       "ssl_version"
204           Default value: "tlsv1"
205
206           This defines the version of the TLS/SSL protocol to use. Possible
207           values are "sslv2", "sslv3", "tlsv1", "tlsv1_1" and "tlsv1_2".
208
209       "ssl_ciphers"
210           Specify which subset of cipher suites are permissible for this
211           connection, using the standard OpenSSL string format. The default
212           value of Net::LDAPS for ciphers is "ALL", which permits all
213           ciphers, even those that do not encrypt!
214
215       "ssl_cert"
216           Path to client certificate.
217
218           Introduced on Sympa 6.2.
219
220       "ssl_key"
221           Path to the secret key of client certificate.
222
223           Introduced on Sympa 6.2.
224
225       "ca_verify"
226           "none", "optional" or "required". If set to "none", will never
227           verify server certificate. Latter two need appropriate "ca_path"
228           and/or "ca_file" settings.
229
230           Introduced on Sympa 6.2.
231
232       "ca_path"
233           Path to directory store of CA certificates.
234
235           Introduced on Sympa 6.2.
236
237       "ca_file"
238           Path to file store of CA certificates.
239
240           Introduced on Sympa 6.2.
241
242   "generic_sso" paragraph
243       "regexp"
244       "negative_regexp"
245           See "user_table" paragraph.
246
247       "service_name"
248           This is the SSO service name that will be offered to the user in
249           the login banner menu.
250
251       "service_id"
252           This service ID is used as a parameter by Sympa to refer to the SSO
253           service (instead of the service name).
254
255           A corresponding URL on the local web server should be protected by
256           the SSO system; this URL would look like
257           "http://yourhost.yourdomain/sympa/sso_login/inqueue" if the
258           "service_id" is ""inqueue"".
259
260       "http_header_list"
261           Sympa gets user attributes from environment variables coming from
262           the web server. These variables are then cached in the "user_table"
263           database table for later use in authorization scenarios (in
264           structure). You can define a comma-separated list of header field
265           names.
266
267       "http_header_prefix"
268           Only environment variables starting with the defined prefix will be
269           kept.  Another option is to list HTTP header fields explicitly
270           using "http_header_list" parameter.
271
272       "email_http_header"
273           This parameter defines the environment variable that will contain
274           the authenticated user's email address.
275
276       "http_header_value_separator"
277           Default: ";"
278
279           User attributes may be multi-valued (including the user email
280           address. This parameter defines the values separator character(s).
281
282       "logout_url"
283           This optional parameter allows one to specify the SSO logout URL.
284           If defined, Sympa will redirect the user to this URL after the
285           Sympa logout has been performed.
286
287       netID mapping parameters
288
289       The following parameters define how Sympa can check the user email
290       address, either provided by the SSO or by the user themselves:
291
292       "internal_email_by_netid"
293           If set to 1, this parameter makes Sympa use its "netidmap" table to
294           associate net IDs to user email addresses.
295
296       "netid_http_header"
297           This parameter defines the environment variable that will contain
298           the user's identifier. This net ID will then be associated with an
299           email address provided by the user.
300
301       "force_email_verify"
302           If set to 1, this parameter makes Sympa check the user's email
303           address. If the email address was not provided by the
304           authentication module, then the user is requested to provide a
305           valid email address.
306
307       LDAP parameters for generic SSO
308
309       The following parameters define how Sympa can retrieve the user email
310       address; these are useful only in case the "email_http_header" entry
311       was not defined:
312
313       "ldap_host"
314           The LDAP host Sympa will connect to fetch user email. The
315           "ldap_host" include the port number and it may be a comma separated
316           list of redundant hosts.
317
318       "ldap_bind_dn"
319           The DN used to bind to this server. Anonymous bind is used if this
320           parameter is not defined.
321
322       "ldap_bind_password"
323           The password used unless anonymous bind is used.
324
325       "ldap_suffix"
326           The LDAP suffix used when searching user email.
327
328       "ldap_scope"
329           The scope used when searching user email. Possible values are
330           "sub", "base" and "one".
331
332       "ldap_get_email_by_uid_filter"
333           The filter used to perform the email search. It can refer to any
334           environment variables inherited from the SSO module, as shown
335           below.
336
337           Example:
338
339             ldap_get_email_by_uid_filter (mail=[SSL_CLIENT_S_DN_Email])
340
341       "ldap_email_attribute"
342           The attribute name to be used as user canonical email. In the
343           current version of Sympa, only the first value returned by the LDAP
344           server is used.
345
346       "ldap_timeout"
347           The time out for the search.
348
349       TLS parameters
350
351       To support LDAPS (LDAP over SSL/TLS), corresponding parameters in
352       "ldap" paragraph may also be used for "generic_sso".
353
354   "cas" paragraph
355       Note that Sympa will act as a CAS client to validate CAS tickets.
356       During this exchange, Sympa will check the CAS server X.509
357       certificate. Therefore you should ensure that the certificate authority
358       of the CAS server is known by Sympa ; this should be configured through
359       the cafile or capath sympa.conf configuration parameters.
360
361       "regexp"
362       "negative_regexp"
363           See "user_table" paragraph.
364
365       "auth_service_name"
366           The authentication service name. Note that it is used as an
367           identifier in the code; it should therefore be made of alphanumeric
368           characters only, with no space.
369
370       "auth_service_friendly_name"
371           If defined, this string is proposed on the web login banner.
372
373       "host" (OBSOLETE)
374           This parameter has been replaced by "base_url" parameter.
375
376       "base_url"
377           The base URL of the CAS server.
378
379       "non_blocking_redirection"
380           "on" or "off". Default value: "on"
381
382           This parameter only concerns the first access to Sympa services by
383           a user, it activates or not the non blocking redirection to the
384           related CAS server to check automatically if the user as been
385           previously authenticated with this CAS server. The redirection to
386           CAS is used with the CGI parameter "gateway=1" that specifies to
387           CAS server to always redirect the user to the original URL, but
388           just check if the user is logged. If active, the SSO service is
389           effective and transparent, but in case the CAS server is out of
390           order, the access to Sympa services is impossible.
391
392       "login_uri" (OBSOLETE)
393           This parameter has been replaced by the "login_path" parameter.
394
395       "login_path" (OPTIONAL)
396           The login service path.
397
398       "check_uri" (OBSOLETE)
399           This parameter has been replaced by the "service_validate_path"
400           parameter.
401
402       "service_validate_path" (OPTIONAL)
403           The ticket validation service path.
404
405       "logout_uri" (OBSOLETE)
406           This parameter has been replaced by the "logout_path" parameter.
407
408       "logout_path" (OPTIONAL)
409           The logout service path.
410
411       "proxy_path" (OPTIONAL)
412           The proxy service path, only used by the Sympa SOAP server.
413
414       "proxy_validate_path" (OPTIONAL)
415           The proxy validate service path, only used by the Sympa SOAP
416           server.
417
418       LDAP parameters for CAS
419
420       "ldap_host"
421           The LDAP host Sympa will connect to fetch user email when user uid
422           is return by CAS service. The "ldap_host" includes the port number
423           and it may be a comma separated list of redundant hosts.
424
425       "ldap_bind_dn"
426           The DN used to bind to this server. Anonymous bind is used if this
427           parameter is not defined.
428
429       "ldap_bind_password"
430           The password used unless anonymous bind is used.
431
432       "ldap_suffix"
433           The LDAP suffix used when searching user email.
434
435       "ldap_scope"
436           The scope used when searching user email. Possible values are
437           "sub", "base" and "one".
438
439       "ldap_get_email_by_uid_filter"
440           The filter used to perform the email search.
441
442       "ldap_email_attribute"
443           The attribute name to be used as user canonical email. In the
444           current version of Sympa, only the first value returned by the LDAP
445           server is used.
446
447       "ldap_timeout"
448           The time out for the search.
449
450       TLS parameters
451
452       To support LDAPS (LDAP over SSL/TLS), corresponding parameters in ldap
453       paragraph may also be used for cas.
454
455   "cgi" paragraph
456       This paragraph allows Sympa to receive authentication information from
457       the external authentication mechanism through Common Gateway Interface
458       (CGI).  By this, Sympa may use authentication methods not supported by
459       Sympa itself.
460
461       "regexp"
462       "negative_regexp"
463           See "user_table" paragraph.
464
465       "remote_user_variable"
466           The name of the CGI environment variable that contains the e-mail
467           address of the authenticated user.  Note that the name of CGI
468           variable is case-sensitive.
469
470       "auth_scheme"
471           Optional.  If set, authentication is considered successful only if
472           it matches the name of authentication scheme, i.e. value of the
473           "AUTH_TYPE" CGI environment variable.
474
475           The value of this parameter is case-insensitive.
476

FILES

478       $DEFAULTDIR/auth.conf
479           Distribution default.  This file should not be edited.
480
481       $SYSCONFDIR/auth.conf
482       $SYSCONFDIR/<robot name>/auth.conf
483           Configuration files for site-wide default and each robot.
484

SEE ALSO

486       wwsympa(8), sympa_soap_server(8).
487
488       Sympa::Auth.
489

HISTORY

491       Descriptions of parameters were originally taken from the chapter
492       "Authentication" in Sympa, Mailing List Management Software - Reference
493       manual, written by Serge Aumont, Soji Ikeda, Olivier Salaün and David
494       Verdin.
495
496       "cgi" paragraph was introduced on Sympa 6.2.71b.
497
498
499
5006.2.72                            2023-07-22                      AUTH.CONF(5)
Impressum