1AUTH.CONF(5) sympa 6.2.72 AUTH.CONF(5)
2
6 auth.conf - Configuration of authentication mechanisms for web
7 interface of Sympa
8
10 The auth.conf configuration file defines authentication mechanisms for
11 web interface of Sympa.
12 auth.conf structure
14 Each paragraph starts with one of the names "user_table", "ldap",
15 "generic_sso", "cas" or "cgi".
16 The auth.conf file contains directives in the following format:
18 name
20 keyword value
21 keyword value
22 ...
23 name
25 keyword value
26 keyword value
27 ...
28 Comments start with the "#" character at the beginning of a line.
30 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 Succeeding subsections describe available parameters in each paragraph.
37 "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 "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 "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 • 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 • The email attribute is extracted from the directory entry
58 corresponding to the found DN.
59 Here is how to configure the LDAP authentication:
61 "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 "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 Example:
76 host ldap.univ-rennes1.fr:389
78 host ldap0.university.com:389,ldap1.university.com:389,ldap2.university.com:389
80 "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 "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 Example:
93 dc=university,dc=fr
95 "bind_dn"
97 If anonymous bind is not allowed on the LDAP server, a DN and
98 password can be used.
99 "bind_password"
101 This password is used, combined with the "bind_dn" above.
102 "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 Example:
110 (Login = [sender])
112 (|(ID = [sender])(UID = [sender]))
114 "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 Example: a person is described by
123 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 The filters can be:
140 (mail = [sender])
142 (| (mail = [sender])(alternate_email = [sender]) )
144 (| (mail = [sender])(alternate_email = [sender])(alternate = [sender]) )
146 "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 "alternative_email_attribute"
153 Obsoleted.
154 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 "scope"
161 Default value: "sub"
162 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 "base"
167 Search only the base object,
168 "one"
170 Search the entries immediately below the base object,
171 "sub"
173 Search the whole tree below the base object. This is the
174 default.
175 "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 TLS parameters
182 Following parameters are used to provide LDAPS (LDAP over TLS/SSL):
184 "use_ssl" (OBSOLETE)
186 If set to 1, connection to the LDAP server will use LDAPS (LDAP
187 over TLS/SSL).
188 Obsoleted as of Sympa 6.2.15. Use "use_tls" instead.
190 "use_tls"
192 Default value: "none"
193 "ldaps"
195 Use LDAPS (LDAP over TLS/SSL),
196 "starttls"
198 Use StartTLS,
199 "none"
201 TLS (SSL) is disabled.
202 "ssl_version"
204 Default value: "tlsv1"
205 This defines the version of the TLS/SSL protocol to use. Possible
207 values are "sslv2", "sslv3", "tlsv1", "tlsv1_1" and "tlsv1_2".
208 "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 "ssl_cert"
216 Path to client certificate.
217 Introduced on Sympa 6.2.
219 "ssl_key"
221 Path to the secret key of client certificate.
222 Introduced on Sympa 6.2.
224 "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 Introduced on Sympa 6.2.
231 "ca_path"
233 Path to directory store of CA certificates.
234 Introduced on Sympa 6.2.
236 "ca_file"
238 Path to file store of CA certificates.
239 Introduced on Sympa 6.2.
241 "generic_sso" paragraph
243 "regexp"
244 "negative_regexp"
245 See "user_table" paragraph.
246 "service_name"
248 This is the SSO service name that will be offered to the user in
249 the login banner menu.
250 "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 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 "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 "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 "email_http_header"
273 This parameter defines the environment variable that will contain
274 the authenticated user's email address.
275 "http_header_value_separator"
277 Default: ";"
278 User attributes may be multi-valued (including the user email
280 address. This parameter defines the values separator character(s).
281 "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 netID mapping parameters
288 The following parameters define how Sympa can check the user email
290 address, either provided by the SSO or by the user themselves:
291 "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 "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 "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 LDAP parameters for generic SSO
308 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 "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 "ldap_bind_dn"
319 The DN used to bind to this server. Anonymous bind is used if this
320 parameter is not defined.
321 "ldap_bind_password"
323 The password used unless anonymous bind is used.
324 "ldap_suffix"
326 The LDAP suffix used when searching user email.
327 "ldap_scope"
329 The scope used when searching user email. Possible values are
330 "sub", "base" and "one".
331 "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 Example:
338 ldap_get_email_by_uid_filter (mail=[SSL_CLIENT_S_DN_Email])
340 "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 "ldap_timeout"
347 The time out for the search.
348 TLS parameters
350 To support LDAPS (LDAP over SSL/TLS), corresponding parameters in
352 "ldap" paragraph may also be used for "generic_sso".
353 "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 "regexp"
362 "negative_regexp"
363 See "user_table" paragraph.
364 "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 "auth_service_friendly_name"
371 If defined, this string is proposed on the web login banner.
372 "host" (OBSOLETE)
374 This parameter has been replaced by "base_url" parameter.
375 "base_url"
377 The base URL of the CAS server.
378 "non_blocking_redirection"
380 "on" or "off". Default value: "on"
381 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 "login_uri" (OBSOLETE)
393 This parameter has been replaced by the "login_path" parameter.
394 "login_path" (OPTIONAL)
396 The login service path.
397 "check_uri" (OBSOLETE)
399 This parameter has been replaced by the "service_validate_path"
400 parameter.
401 "service_validate_path" (OPTIONAL)
403 The ticket validation service path.
404 "logout_uri" (OBSOLETE)
406 This parameter has been replaced by the "logout_path" parameter.
407 "logout_path" (OPTIONAL)
409 The logout service path.
410 "proxy_path" (OPTIONAL)
412 The proxy service path, only used by the Sympa SOAP server.
413 "proxy_validate_path" (OPTIONAL)
415 The proxy validate service path, only used by the Sympa SOAP
416 server.
417 LDAP parameters for CAS
419 "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 "ldap_bind_dn"
426 The DN used to bind to this server. Anonymous bind is used if this
427 parameter is not defined.
428 "ldap_bind_password"
430 The password used unless anonymous bind is used.
431 "ldap_suffix"
433 The LDAP suffix used when searching user email.
434 "ldap_scope"
436 The scope used when searching user email. Possible values are
437 "sub", "base" and "one".
438 "ldap_get_email_by_uid_filter"
440 The filter used to perform the email search.
441 "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 "ldap_timeout"
448 The time out for the search.
449 TLS parameters
451 To support LDAPS (LDAP over SSL/TLS), corresponding parameters in ldap
453 paragraph may also be used for cas.
454 "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 "regexp"
462 "negative_regexp"
463 See "user_table" paragraph.
464 "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 "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 The value of this parameter is case-insensitive.
476
478 $DEFAULTDIR/auth.conf
479 Distribution default. This file should not be edited.
480 $SYSCONFDIR/auth.conf
482 $SYSCONFDIR/<robot name>/auth.conf
483 Configuration files for site-wide default and each robot.
484
486 wwsympa(8), sympa_soap_server(8).
487 Sympa::Auth.
489
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 "cgi" paragraph was introduced on Sympa 6.2.71b.
4976.2.72 2023-07-22 AUTH.CONF(5)