Incubating the new Sympa documentation site

Authentication on web interface

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 account with user and password, it can validate these credentials against authentication backends.

Authentication mechanisms

On the web interface (WWSympa), the user can authenticate in four different authentication mechanisms (if appropriate setup has been done on the Sympa server):

The authorization process in Sympa (authorization scenarios) refers to authentication methods. The same authorization scenarios are used for both mail and web accesses; therefore some authentication methods are considered to be equivalent: See “Authentication methods”.

Built-in authentication mechanism

By default, only this mechanism is enabled.

Sympa stores the data relative to users in the user_table database table. Among these data, password and email address are used during the web authentication.

Built-in authentication mechanism is described by user_table paragraph in auth.conf configuration file. Below is an example of the paragraph:

    negative_regexp             ((univ-rennes1)|(univ-nancy2))\.fr

See “Built-in authentication” for more details.

LDAP authentication

Authentication based on information stored in LDAP directory. This mechanism may be defined by ldap paragraph in auth.conf configuration file. See “LDAP authentication” for more details.

CAS single sign-on

See “CAS single sign-on” for details.

Generic SSO authentication

This authentication mechanism has first been introduced to allow interaction with Shibboleth, Internet2’s inter-institutional authentication system. But it should be usable with any SSO system that provides an Apache HTTP Server’s authentication module being able to protect a specified URL on the site (not the whole site).

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).

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

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. Once this paragraph has been added, the SSO service name will be automatically added to the web login menu.

Below is an example of the paragraph:

## The URL corresponding to the service_id should be protected by the SSO (Shibboleth in the example)
## The URL would look like http://yourhost.yourdomain/sympa/sso_login/inqueue in
 the following example
    service_name                InQueue Federation
    service_id                  inqueue
    http_header_list            mail,displayName,eduPersonAffiliation
    email_http_header           mail

## The email address is not provided by the user home institution
    service_name                Shibboleth Federation
    service_id                  myfederation
    http_header_list            mail,displayName,eduPersonAffiliation
    netid_http_header           mail
    internal_email_by_netid     1
    force_email_verify          1

And here is a sample httpd.conf that Shibboleth authentication protects the associated Sympa URL:

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

For detailed description to integrate Sympa into Shibboleth and its federation, see “Setting up a Shibboleth-enabled Sympa server”.

TLS client authentication

See “TLS client authentication for details.

Sympa configuration overview


The auth.conf configuration file contains numerous parameters which are read on start-up of Sympa. Its location is:

See also “Configuration files.




The 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.

regexp and negative_regexp: The auth.conf switches

Suppose your organization use two domains for its email addresses, for example “” and “”. The first domain correspond to people stored in a part of the LDAP directory , and the other one to people stored in another part. You may want to define a specific authentication paragraph for each of these groups.

the regexp subparameter — and its evil twin negative_regexp — are exactly used to perform such a distinction: it allows you to apply different authentication paragraph based on which email address was provided by the user. Let’s emphasize this: The regexp and negative_regexp are applied to email addresses only. It will not work on user ID.

Each paragraph in auth.conf can contain an occurence of these subparameters. Their value is a regexp (just the regexp part. No delimiters).


regexp         student\.univ\.edu

What do they do?

They are tested among the domain part of the email provided. The paragraph will be used with this email address if it matches the expression defined by regexp or if it does not match the expression defined by negative_regexp.

Login form

The login page contains two forms: the login form and the SSO form. 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 authemtication mechanisms for a class of users.

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

Sharing WWSympa’s authentication with other applications

(Work in progress)

Perl example

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 :


## Just a example how to use Sympa Session.

use strict;
use warnings;
use lib '$LIBDIR';    # Replace with actual path.

use Conf;
use Sympa::DatabaseManager;
use Sympa::Session;

my $robot = '';    # Replace with actual mail domain.
my $email;

unless (Conf::load()) {
    die "Configuration file sympa.conf has errors.\n";
unless (Sympa::DatabaseManager->instance) {
    die "Error could not connect to database";

if ($ENV{HTTP_COOKIE} =~ /(sympa_session)=/) {
    my $session = Sympa::Session->new($robot,
        {cookie => Sympa::Session::get_session_cookie($ENV{HTTP_COOKIE})});
    $email = $session->{email}
        if $session->{email} and $session->{email} ne 'nobody';

print "Content-Type: text/html\n\n";
print '<html><head><title>Just a test</head><body>';

if ($email) {

    printf <<"EOF";

  Sympa session is recognized from cookie sympa_session.
  Your email is <strong>$email</strong>.

} else {

    print <<'EOF';
<h1> method 1: Use Sympa form</h1>

  This method is very simple, just link the Sympa login page using the
  <i>referer</i> parameter.
  The URL look like
  <a href="/sympa/loginrequest/referer">Try it</a>

<h1>method 2: Copy login form into your application</h1>

<form action="" method="POST">
  <input type="hidden" name="referer"
   value="" />
  <input type="hidden" name="failure_referer"
   value="" />
  <input type="hidden" name="action" value="login" />
    <label for="email">email address:</label>
    <input type="text" name="email" id="email" />
    <label for="passwd" >password:</label>
    <input type="password" name="passwd" id="passwd" />
    <input type="submit" name="action_login" value="Login" />


print '</body></html>';

How to do it using PHP ?

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

What about using SOAP/HTTP API to access Sympa sessions

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

Provide a Sympa login form in another application

You can easily trigger a Sympa login from another web page. The login form should look like this:

<form action="" method="POST">
  <input type="hidden" name="previous_action" value="arc" />
    Access web archives of list
    <select name="previous_list">
      <option value="sympa-users" >sympa-users</option>
  <input type="hidden" name="action" value="login" />
    <label for="email">email address:</label>
    <input type="text" name="email" id="email" size="18" />
    <label for="passwd" >password:</label>
    <input type="password" name="passwd" id="passwd" size="8" />
    <input class="MainMenuLinks" type="submit" name="action_login"
     value="Login and access web archives" />

The example above does not only perform the login action, but also redirects the user to another Sympa page, a list web archive here. The previous_action and previous_list variables define the action that will be performed after the login is done.

CC BY-SA 4.0 Unless otherwise specified, the contents of this document are licensed under the Creative Commons - Attribution - ShareAlike license. For more details see LICENSE and AUTHORS.

Theme originally designed by orderedlist