Sympa needs to authenticate users (subscribers, owners, moderators, listmasters) on both its mail and web interface, and then apply appropriate privileges (authorization process) to subsequent requested actions. Sympa is able to cope with multiple authentication means on the client side, and when using user+password, it can validate these credentials against LDAP authentication backends.

When contacted on the mail interface, Sympa has 3 authentication levels. Lower level is to trust the From: SMTP header field. A higher level of authentication will require that the user confirms his/her message. The strongest supported authentication method is S/MIME (note that Sympa also deals with S/MIME encrypted messages).

On the Sympa web interface (WWSympa) the user can authenticate in 4 different ways (if appropriate setup has been done on the Sympa server). Default authentication is performed through the user's email address and a password managed by Sympa itself. If an LDAP authentication backend (or multiple) has been defined, then the user can authenticate with his/her LDAP uid and password. Sympa is also able to delegate the authentication job to a web Single SignOn system; currently CAS (the Yale University system) or a generic SSO setup, adapted to SSO products providing an Apache module. When contacted via HTTPS, Sympa can make use of X509 client certificates to authenticate users.

The authorization process in Sympa (authorization scenarios) refers to authentication methods. The same authorization scenarios are used for both mail and web accesss; therefore some authentication methods are considered to be equivalent: mail confirmation (on the mail interface) is equivalent to password authentication (on the web interface); S/MIME authentication is equivalent to HTTPS with client certificate authentication. Each rule in authorization scenarios requires an authentication method (smtp, md5 or smime); if the required authentication method was not used, a higher authentication mode can be requested.

Chapter Use of S/MIME signature by Sympa itself deals with Sympa and S/MIME signature. Sympa uses the OpenSSL library to work on S/MIME messages, you need to configure some related Sympa parameters: S/X509 Sympa configuration.

Sympa HTTPS authentication is based on Apache+mod_SSL that provide the required authentication information through CGI environment variables. You will need to edit the Apache configuration to allow HTTPS access and require X509 client certificate. Here is a sample Apache configuration:

  SSLEngine on
  SSLVerifyClient optional
  SSLVerifyDepth  10
  ...
  <Location /sympa>
     SSLOptions +StdEnvVars
     SetHandler fastcgi-script
  </Location>

If you are using the SubjAltName, then you additionaly need to export the certificate data because of a mod_ssl bug. You will also need to install the textindex Crypt-OpenSSL-X509 CPAN module. Add this option to the Apache configuration file:

SSLOptions +ExportCertData

Sympa stores the data relative to the subscribers in a DataBase. Among these data: password, email address exploited during the web authentication. The module of LDAP authentication allows to use Sympa in an intranet without duplicating user passwords.

This way users can indifferently authenticate with their ldap_uid, their alternate_email or their canonic email stored in the LDAP directory.

Sympa gets the canonic email in the LDAP directory with the ldap_uid or the alternate_email. Sympa will first attempt an anonymous bind to the directory to get the user's DN, then Sympa will bind with the DN and the user's ldap_password in order to perform an efficient authentication. This last bind will work only if the right ldap_password is provided. Indeed the value returned by the bind(DN,ldap_password) is tested.

Example: a person is described by

                 Dn:cn=Fabrice Rafart,
                 ou=Siege ,
                 o=MyCompany,
                 c=FR Objectclass:
                 person Cn: Fabrice Rafart
                 Title: Network Responsible
                 O: Siege
                 Or: Data processing
                 Telephonenumber: 01-00-00-00-00
                 Facsimiletelephonenumber:01-00-00-00-00
                 L:Paris
                 Country: France
		       uid: frafart
 		       mail: Fabrice.Rafart@MyCompany.fr
                 alternate_email: frafart@MyCompany.fr
                 alternate:rafart@MyCompany.fr

So Fabrice Rafart can be authenticated with: frafart, Fabrice.Rafart@MyCompany.fr, frafart@MyCompany.fr, Rafart@MyCompany.fr. After this operation, the address in the FROM field will be the Canonic email, in this case Fabrice.Rafart@MyCompany.fr. That means that Sympa will get this email and use it during all the session until you clearly ask Sympa to change your email address via the two pages: which and pref.

The authentication method has first been introduced to allow interraction with Shibboleth, Internet2's inter-institutional authentication system. But it should be usable with any SSO system that provides an Apache authentication module being able to protect a specified URL on the site (not the whole site). Here is a sample httpd.conf that shib-protects the associated Sympa URL:

  ...
  <Location /sympa/sso_login/inqueue>
    AuthType shibboleth
    require mail ~ @
  </Location>
  ...

Sympa will get user attributes via environment variables. In the most simple case, the SSO will provide the user email address. If not, Sympa can be configured to check an email address provided by the user, or to look for the user email address in a LDAP directory (the search filter will make use of user information inherited from the SSO Apache module).

To plug a new SSO server in your Sympa server, you should add a generic_sso paragraph (describing the SSO service) in your auth.conf configuration file (see generic_sso paragraph). Once this paragraph has been added, the SSO service name will be automatically added to the web login menu.

Apart from the user email address, the SSO can provide other user attributes that Sympa will store in the user_table DB table (for persistancy), and make available in the [user_attributes] structure that you can use within authorization scenarios (see Rules specifications) or in web templates via the [% user.attributes %] structure.

CAS is the Yale University SSO software. Sympa can use the CAS authentication service.

Listmasters should define at least one or more CAS servers (cas paragraph) in auth.conf. If the non_blocking_redirection parameter was set for a CAS server, then Sympa will try a transparent login on this server when the user accesses the web interface. If a CAS server redirects the user to Sympa with a valid ticket, Sympa receives a user ID from the CAS server. Then, it connects to the related LDAP directory to get the user email address. If no CAS server returns a valid user ID, Sympa will let the user either select a CAS server to login or perform a Sympa login.

The /home/sympa/etc/auth.conf configuration file contains numerous parameters which are read on start-up of Sympa. If you change this file, do not forget that you will need to restart wwsympa.fcgi afterwards.

The /home/sympa/etc/auth.conf is organized in paragraphs. Each paragraph describes an authentication service with all parameters required to perform an authentication using this service. Sympa's current version can perform authentication through LDAP directories, using an external Single Sign-On Service (like CAS or Shibboleth), or using the internal user_table table.

The login page contains 2 forms: the login form and the SSO. When users hit the login form, each ldap or user_table authentication paragraph is applied unless email adress input from form matches the negative_regexp or do not match regexp. negative_regexp and regexp can be defined for each ldap or user_table authentication service so that administrators can block some authentication methods for a class of users.

The second form in the login page contains the list of CAS servers so that users can choose explicitely their CAS service.

Each paragraph starts with one of the keyword cas, ldap or user_table.

The /home/sympa/etc/auth.conf file contains directives in the following format:

paragraphs
keyword value

paragraphs
keyword value

Comments start with the # character at the beginning of a line.

Empty lines are also considered as comments and are ignored at the beginning. After the first paragraph, they are considered as paragraph separators. There should only be one directive per line, but their order in the paragraph is of no importance.

Example:

  #Configuration file auth.conf for the LDAP authentification
  #Description of parameters for each directory
  
  cas
  	base_url			https://sso-cas.cru.fr
  	non_blocking_redirection        on
  	auth_service_name		cas-cru
  	ldap_host			ldap.cru.fr:389
          ldap_get_email_by_uid_filter    (uid=[uid])
  	ldap_timeout			7
  	ldap_suffix			dc=cru,dc=fr
  	ldap_scope			sub
  	ldap_email_attribute		mail
  
  ## The URL corresponding to the service_id should be protected by the SSO (Shibboleth in the exampl)
  ## The URL would look like http://yourhost.yourdomain/sympa/sso_login/inqueue in the following example
  generic_sso
          service_name       InQueue Federation
          service_id         inqueue
          http_header_prefix HTTP_SHIB
          email_http_header  HTTP_SHIB_EMAIL_ADDRESS
  
  ## The email address is not provided by the user home institution
  generic_sso
          service_name               Shibboleth Federation
          service_id                 myfederation
          http_header_prefix         HTTP_SHIB
          netid_http_header          HTTP_SHIB_EMAIL_ADDRESS
  	internal_email_by_netid    1
  	force_email_verify         1
  
  ldap
  	regexp				univ-rennes1\.fr
  	host				ldap.univ-rennes1.fr:389
  	timeout				30
  	suffix				dc=univ-rennes1,dc=fr
  	get_dn_by_uid_filter		(uid=[sender])
  	get_dn_by_email_filter		(|(mail=[sender])(mailalternateaddress=[sender]))
  	email_attribute			mail
  	alternative_email_attribute	mailalternateaddress,ur1mail
  	scope				sub
  	use_ssl                         1
  	ssl_version                     sslv3
  	ssl_ciphers                     MEDIUM:HIGH
  
  ldap  
  	host				ldap.univ-nancy2.fr:392,ldap1.univ-nancy2.fr:392,ldap2.univ-nancy2.fr:392
  	timeout				20
  	bind_dn                         cn=sympa,ou=people,dc=cru,dc=fr
  	bind_password                   sympaPASSWD
  	suffix				dc=univ-nancy2,dc=fr
  	get_dn_by_uid_filter		(uid=[sender])
  	get_dn_by_email_filter			(|(mail=[sender])(n2atraliasmail=[sender]))
  	alternative_email_attribute	n2atrmaildrop
  	email_attribute			mail
  	scope				sub
          authentication_info_url         http://sso.univ-nancy2.fr/
  
  user_table
  	negative_regexp 		((univ-rennes1)|(univ-nancy2))\.fr

The user_table paragraph is related to Sympa internal authentication by email and password. It is the simplest one. The only parameters are regexp or negative_regexp which are Perl regular expressions applied on an email address provided, to select or block this authentication method for a subset of email addresses.

• regexp and negative_regexp
  Same as in the user_table paragraph: if an email address is provided (this does not apply to an uid), then the regular expression will be applied to find out if the LDAP directory can be used to authenticate a subset of users.
• host
  This keyword is mandatory. It is the domain name used in order to bind to the directory and then to extract information. You must mention the port number after the server name. Server replication is supported by listing several servers separated by commas.
  Example:

    	host ldap.univ-rennes1.fr:389
    	host ldap0.university.com:389,ldap1.university.com:389,ldap2.university.com:389

• timeout
  It corresponds to the timelimit in the Search fonction. A timelimit that restricts the maximum time (in seconds) allowed for a search. A value of 0 (the default) means that no timelimit will be requested.
• suffix
  The root of the DIT (Directory Information Tree). The DN that is the base object entry relative to which the search is to be performed.
  Example: dc=university,dc=fr
• bind_dn
  If anonymous bind is not allowed on the LDAP server, a DN and password can be used.
• bind_password
  This password is used, combined with the bind_dn above.
• get_dn_by_uid_filter
  Defines the search filter corresponding to the ldap_uid. (RFC 2254 compliant). If you want to apply the filter on the user, use the variable ' [sender] '. It will work with every type of authentication (uid, alternate_email, ...).
  Example:

 	(Login = [sender])
    	(|(ID = [sender])(UID = [sender]))

• get_dn_by_email_filter
  Defines the search filter corresponding to the email addresses (canonic and alternative - this is RFC 2254 compliant). If you want to apply the filter on the user, use the variable ' [sender] '. It will work with every type of authentication (uid, alternate_email..).
  Example: a person is described by

  Dn:cn=Fabrice Rafart,
  ou=Siege ,
  o=MaSociete ,
  c=FR Objectclass:
  person Cn: Fabrice Rafart
  Title: Network Responsible
  O: Siege
  Or: Data processing
  Telephonenumber: 01-00-00-00-00
  Facsimiletelephonenumber:01-00-00-00-00
  L:Paris
  Country: France
  uid: frafart
  mail: Fabrice.Rafart@MaSociete.fr
  alternate_email: frafart@MaSociete.fr
  alternate:rafart@MaSociete.fr

The filters can be:

  (mail = [sender]) (| (mail = [sender])(alternate_email = [sender]) )
  (| (mail = [sender])(alternate_email = [sender])(alternate  = [sender]) )

• email_attribute
  The name of the attribute for the canonic email in your directory: for instance mail, canonic_email, canonic_address, ... In the previous example, the canonic email is mail.
• alternative_email_attribute
  The name of the attribute for the alternate email in your directory: for instance alternate_email, mailalternateaddress, ... You make a list of these attributes separated by commas.

With this list, Sympa creates a cookie which contains various information: whether the user is authenticated via LDAP or not, his alternate email. Storing the alternate email is interesting when you want to canonify your preferences and subscriptions, that is to say you want to use a unique address in user_table and subscriber_table, which is the canonic email.

• scope (Default value: sub)
  By default, the search is performed on the whole tree below the specified base object. This may be changed by specifying a scope:
  • base: search only the base object,
  • one: search the entries immediately below the base object,
  • sub: search the whole tree below the base object. This is the default.
• authentication_info_url
  Defines the URL of a document describing LDAP password management. When hitting Sympa's Send me a password button, LDAP users will be redirected to this URL.
• use_ssl
  If set to 1, connection to the LDAP server will use SSL (LDAPS).
• ssl_version
  This defines the version of the SSL/TLS protocol to use. Defaults of Net::LDAPS to sslv2/3, other possible values are sslv2, sslv3, and tlsv1.
• ssl_ciphers

Specify which subset of cipher suites are permissible for this connection, using the standard OpenSSL string format. The default value of Net::LDAPS for ciphers is ALL, which permits all ciphers, even those that do not encrypt!

• service_name
  This is the SSO service name that will be offered to the user in the login banner menu.
• service_id
  This service ID is used as a parameter by Sympa to refer to the SSO service (instead of the service name).
  A corresponding URL on the local web server should be protected by the SSO system; this URL would look like http://yourhost.yourdomain/sympa/sso_login/inqueue if the service_id is inqueue.
• http_header_prefix
  Sympa gets user attributes from environment variables coming from the web server. These variables are then stored in the user_table DB table for later use in authorization scenarios (in structure). Only environment variables starting with the defined prefix will be kept.
• email_http_header
  This parameter defines the environment variable that will contain the authenticated user's email address.
• logout_url
  This optional parameter allows to specify the SSO logout URL. If defined, Sympa will redirect the user to this URL after the Sympa logout has been performed.

The following parameters define how Sympa can check the user email address, either provided by the SSO or by the user himself:

• internal_email_by_netid
  If set to 1, this parameter makes Sympa use its netidmap table to associate NetIDs to user email addresses.
• netid_http_header
  This parameter defines the environment variable that will contain the user's identifier. This netid will then be associated with an email address provided by the user.
• force_email_verify
  If set to 1, this parameter makes Sympa check the user's email address. If the email address was not provided by the authentication module, then the user is requested to provide a valid email address.

The following parameters define how Sympa can retrieve the user email address; these are useful only in case the email_http_header entry was not defined:

• ldap_host
  The LDAP host Sympa will connect to fetch user email. The ldap_host include the port number and it may be a comma separated list of redondant hosts.
• ldap_bind_dn
  The DN used to bind to this server. Anonymous bind is used if this parameter is not defined.
• ldap_bind_password
  The password used unless anonymous bind is used.
• ldap_suffix
  The LDAP suffix used when searching user email.
• ldap_scope
  The scope used when searching user email. Possible values are sub, base and one.
• ldap_get_email_by_uid_filter
  The filter used to perform the email search. It can refer to any environment variables inherited from the SSO module, as shown below. Example:

  ldap_get_email_by_uid_filter    (mail=[SSL_CLIENT_S_DN_Email])

• ldap_email_attribute
  The attribute name to be used as user canonical email. In the current version of Sympa, only the first value returned by the LDAP server is used.
• ldap_timeout
  The time out for the search.
• ldap_use_ssl
  If set to 1, connection to the LDAP server will use SSL (LDAPS).
• ldap_ssl_version
  This defines the version of the SSL/TLS protocol to use. Defaults of Net::LDAPS to sslv2/3, other possible values are sslv2, sslv3, and tlsv1.
• ldap_ssl_ciphers
  Specifies which subset of cipher suites are permissible for this connection, using the OpenSSL string format. The default value of Net::LDAPS for ciphers is ALL, which permits all ciphers, even those that do not encrypt!

Note that Sympa will act as a CAS client to validate CAS tickets. During this exchange, Sympa will check the CAS server x.509 certificate. Therefore you should ensure that the certificate autority of the CAS server is known by Sympa ; this should be configured through the cafile or capath sympa.conf configuration parameters.

• auth_service_name
  The friendly user service name as shown by Sympa in the login page.
• host (OBSOLETE)
  This parameter has been replaced by base_url parameter
• base_url
  The base URL of the CAS server.
• non_blocking_redirection
  This parameter only concerns the first access to Sympa services by a user, it activates or not the non blocking redirection to the related CAS server to check automatically if the user as been previously authenticated with this CAS server. Possible values are on and off, default is on. The redirection to CAS is used with the CGI parameter gateway=1 that specifies to CAS server to always redirect the user to the original URL, but just check if the user is logged. If active, the SSO service is effective and transparent, but in case the CAS server is out of order, the access to Sympa services is impossible.
• login_uri (OBSOLETE)
  This parameter has been replaced by the login_path parameter.
• login_path (OPTIONAL)
  The login service path.
• check_uri (OBSOLETE)
  This parameter has been replaced by the service_validate_path parameter.
• service_validate_path (OPTIONAL)
  The ticket validation service path.
• logout_uri (OBSOLETE)
  This parameter has been replaced by the logout_path parameter.
• logout_path (OPTIONAL)
  The logout service path.
• proxy_path (OPTIONAL)
  The proxy service path, only used by the Sympa SOAP server.
• proxy_validate_path (OPTIONAL)
  The proxy validate service path, only used by the Sympa SOAP server.
• ldap_host
  The LDAP host Sympa will connect to fetch user email when user uid is return by CAS service. The ldap_host includes the port number and it may be a comma separated list of redondant hosts.
• ldap_bind_dn
  The DN used to bind to this server. Anonymous bind is used if this parameter is not defined.
• ldap_bind_password
  The password used unless anonymous bind is used.
• ldap_suffix
  The LDAP suffix used when searching user email.
• ldap_scope
  The scope used when searching user email. Possible values are sub, base and one.
• ldap_get_email_by_uid_filter
  The filter used to perform the email search.
• ldap_email_attribute
  The attribute name to be used as user canonical email. In the current version of Sympa, only the first value returned by the LDAP server is used.
• ldap_timeout
  The time out for the search.
• ldap_use_ssl
  If set to 1, connection to the LDAP server will use SSL (LDAPS).
• ldap_ssl_version
  This defines the version of the SSL/TLS protocol to use. Defaults of Net::LDAPS to sslv2/3, other possible values are sslv2, sslv3, and tlsv1.
• ldap_ssl_ciphers
  Specifies which subset of cipher suites are permissible for this connection, using the OpenSSL string format. The default value of Net::LDAPS for ciphers is ALL, which permits all ciphers, even those that do not encrypt!

If you are not using a web Single Sign On system, you might want to make other web applications collaborate with Sympa and share the same authentication system. Sympa uses HTTP cookie to identify each user session and stores information about the current session into a table name session_table.

Delegating authentication operations to WWSympa. If you want to avoid spending a lot of time programming a CGI to do Login, Logout and Resetpassword you can copy WWSympa's login page to your application, and then make use of the cookie information within your application. If you are programming using perl the best way for it is use SympaSession.pm module. It is described into internals session of the internal documentation. You may also do it with some other programming langage such as perl or whatever.

WWSympa's loginrequest page can be called to return to the referer URL when an action is performed. Here is a sample HTML anchor:

<A HREF=''/sympa/loginrequest/referer''>Login page</A>

You can also have your own HTML page submitting data to wwsympa.fcgi CGI. If you do so, you can set the referer variable to another URI. You can also set the failure_referer to make WWSympa redirect the client to a different URI if login fails.

Here is a example using perl that show both method : use Sympa login page or copy login form into your application. You can try it on Sympa author's lists server : http://listes.cru.fr/cgi-bin/sample.cgi

#!/usr/bin/perl -U
 
## Just a example how to use Sympa Session
 
use strict;
use CGI;
use DBI;
use lib '/home/sympa/bin';
use Conf;
use SympaSession;
# use cookielib;
use List;
my $query = new CGI;
my %in = $query->Vars;
my $robot = 'cru.fr';
my $email;
 
unless (&Conf::load('/etc/sympa.conf')) {
    printf "Configuration file /etc/sympa.conf has errors.\n";
}
### this section is mandatory to have List::is_user working
if ($Conf{'db_name'} and $Conf{'db_type'}) {
    unless ($List::use_db = &Upgrade::probe_db()) {
	printf "Error could not connect to database";
    }
}
&List::_apply_defaults();
print "Content-Type: text/html\n\n";
print "<html><head><title>just a test</head><body>";
if ($ENV{'HTTP_COOKIE'} =~ /(sympa_session)\=/) {   
    my  $session = new SympaSession ($robot,{'cookie'=>&SympaSession::get_session_cookie($ENV{'HTTP_COOKIE'})});
    $email = $session->{'email'} unless ($session->{'email'} eq 'nobody');
}
printf "<h1>welcome</h1>";
if ($email) {
    printf "Sympa session is recognized from cookie sympa_session. Your email is <b>%s</b>\n",$email;
}else{
print '
<h4> method 1: use Sympa form</h4>
This method is very simple, just link the Sympa login page using the <i>referer</i> parameter. 
The URL look like http://mysserver.domain.org/sympa/loginrequest/referer.   
<a href="/sympa/loginrequest/referer">Try it</a>
 
<h4>method 2 : copy login form into your application</h4>
  <form action="http://listes.cru.fr/sympa" method="post">
        <input type="hidden" name="referer" value="http://myserver.domain.org/cgi-bin/sample.cgi" /> 
        <input type="hidden" name="failure_referer" value " http://myserver.domain.org/cgi-bin/error_login.html" />
        <input type="hidden" name="action" value="login" />
        <label for="email">email address:
        <input type="text" name="email" id="email"/></label><br />
        <label for="passwd" >password:
        <input type="password" name="passwd" id="passwd" /></label> <br/>
        <input type="submit" name="action_login" value="Login" />
  </form>';
}
print '</body></hml>';

Chris Hastie has sumitted a contrib for sharing Sympa sessions with PHP applications.

Not yet possible but of course this the best way to do it. There is a feature request for it.