Skip to Content.
Sympa Menu

Authorization scenarios

The authorization scenario (or simply "scenario") is a small configuration language. It describes authorization for each operation of Sympa based on various conditions such as actors and authentication methods.

Location of scenario file

Each scenario file is named as "function.name". The function corresponds to a function to be authorized, and the name distinguishes the policy. Usually, some scenario files with different names are prepared for each function.

For example, a scenario file

subscribe.open

may be used to make subscription of a list be open. To do such,

To look for a particular scenario, Sympa searches following directories in order (see also "Configuration files"):

You can modify Sympa behavior if you create a new scenario with the same name as one of the scenario already included in the distribution but with a location related to the target site, domain or list. You can also add a new scenario ; it will automatically add an accepted value for the related parameter.

See also "Hiding scenario files".

Note

  • When customizing a scenario for your own site, domain or list, don't modify $DEFAULTDIR/scenari content or the next Sympa update will overwrite it (you must never modify anything in $DEFAULTDIR unless you are patching Sympa).

  • When modifying an existing scenario you need to restart Sympa or touch list config file before Sympa use it.

Content of scenario file

Basically, a scenario file is composed of one or more titles on the first lines and a set of rules on the following lines. For example:

title.en-US deletion performed only by list owners, need authentication
title.es eliminacin reservada slo para el propietario, necesita autentificacin
title.fr suppression réservée au propriétaire avec authentification

is_owner([listname],[sender])  smtp       -> request_auth
is_listmaster([sender])        smtp       -> request_auth
true()                         md5,smime  -> do_it

Scenario title

The first line of a scenario file can contains its own title. This is the text that will later appear in the drop-down menu of your management web interface. This title can be just plain text:

title Restricted to subscribers

It can also be set to be internationalized:

title Restricted to subscribers
title.en-US Restricted to subscribers
title.es restringido a subscriptores
title.fr limité aux abonnés

or

title.gettext Restricted to subscribers

In the first example, appropriate title.lang line will be used for title according to users' language context (see also "Language tag"). If no appropriate line is found, title will be used as default. In the second, the string following title.gettext will be translated to the users' language using Sympa's translation catalog. If there are no entry in catalog, the string itself will be used.

Rules

Note

One or more lines for rules follow to title. Each rule has the following syntax:

condition authentication_methods -> action

Rules are evaluated in order, and once a rule matching with given condition and authentication method is found, action will be returned and subsequent rules will no longer be evaluated.

Conditions

A condition is the term with optional arguments. Each argument may be a variable with a given value according to context, or a literal string.

For example:

You can also create custom conditions by writing a Perl module: See "Custom scenario conditions" for details.

Authentication methods

You can specify four different authentication methods to base your rules on (ordered from lower to higher levels):

If the specified authentication method was not used, a higher level of authentication methods can be requested.

These methods take a different meaning if you consider them in a web or mail context. For example with the scenario send which will be evaluated when people try to send a message to a list:

However the same scenario file will be used in both cases. That means that the same authentication method will be used, whichever context we're in. It is consequently important to understand what interpretation to give to each authentication method according to the context.

Here is a description of what is evaluated to authenticate the user depending of the context: web or mail.

Method Mail context Web context
smtp sender ("From:" field etc.) in the message header anonymous user (nobody)
md5 confirmation/approval with the authentication key in the message [1] authentication mechanisms with username/password
smime valid S/MIME signature of the message [2] TLS client authentication with X.509 certificate installed in the user's browser

In most cases, smtp will be used for mails, and md5 for the web.

Note

Actions

An action is one of following keywords:

Some actions may have modifiers, for example:

editorkey,quiet

do_it,notify

reject(reason='subscribe_closed')

reject(tt2='custom_response')

This is an important issue to prevent backscatter messages. Backscatter messages are messages you receive as an automatic answer to a message you never sent. The following web page give you more details :

Named Filters

At the moment, Named Filters are only used in authorization scenarios. They enable to select a category of people who will be authorized or not to realize some actions.

As a consequence, you can grant privileges in a list to people belonging to an LDAP directory, an SQL database or a flat text file, thanks to an authorization scenario.

Note that only a subset of variables available in the scenario context are available here (including [sender] and [listname]).

LDAP Named Filters Definition

People are selected through an LDAP filter defined in a configuration file. This file must have the extension '.ldap'. It is stored in $SYSCONFDIR/search_filters/.

You must provide some information in order to create a LDAP Named Filter:

example.ldap: we want to select the teachers of mathematics in the University of Rennes 1 in France:

host        ldap.univ-rennes1.fr:389,ldap2.univ-rennes1.fr:390
suffix      dc=univ-rennes1.fr,dc=fr
filter      (&(canonic_mail = [sender])(EmployeeType = prof)(subject = math))
scope       sub

SQL Named Filters Definition

People are selected through an SQL filter defined in a configuration file. This file must have the extension '.sql'. It is stored in $SYSCONFDIR/search_filters/.

To create an SQL Named Filter, you have to configure SQL host, database and options, the same way you did it for the main Sympa database in sympa.conf. Of course, you can use different database and options. Sympa will open a new Database connection to execute your statement.

Please refer to section "Database related" for a detailed explanation of each parameter.

Here, all database parameters have to be grouped in one sql_named_filter_query paragraph.

example.sql: we want to select the teachers of mathematics in the University of Rennes 1 in France:

sql_named_filter_query
  db_type         mysql
  db_name         people
  db_host         dbserver.rennes1.fr
  db_user         sympa
  db_passwd       pw_sympa_mysqluser
  statement       SELECT count(*) as c FROM users WHERE mail=[sender] AND EmployeeType='PROFESSOR' AND department='mathematics'

Search condition

The search condition is used in authorization scenarios.

The syntax of this rule is:

search(example.ldap)      smtp,md5,smime    -> do_it
search(example.txt)       smtp,md5,smime    -> do_it

The variable used by search is the name of the LDAP configuration file or a txt matching enumeration.

Note that Sympa processes maintain a cache of processed search conditions to limit access to the LDAP directory or SQL server; each entry has a lifetime of one hour in the cache.

When using the '.txt' file extension, each line is used to try to match the sender email address. You can use the "*" character as a wild card to replace any string.

Here is an example of such a file:

david.verdin@renater.fr
*salaun*

With such a file, the rule would be true for the following email addresses:

It would be false for the following email addresses :

This feature is used by the blocklist implicit scenario rule (see "Blocklist implicit rule").

The method of authentication does not change.

Scenario inclusion

Scenarios can also contain includes:

include commonreject
match([sender], /cru\.fr$/)          smtp,smime -> do_it
true()                               smtp,smime -> owner

In this case, Sympa applies recursively the scenario named include.commonreject before introducing the other rules. This possibility was introduced in order to facilitate the administration of common rules.

Scenario implicit inclusion

You can define a set of common scenario rules, used by all lists. include.<action>.header is automatically added to evaluated scenarios. Note that you will need to restart Sympa processes to force reloading of list config files.

Blocklist implicit rule

For each service listed in parameter use_blocklist, the following implicit scenario rule is added at the beginning of the scenario:

search(blocklist.txt)  smtp,md5,smime -> reject,quiet

The goal is to block messages or other service requests from unwanted users. The blocklist can be defined for the domain or for the list. At the list level, the blocklist is to be managed by the list owner or the list moderator via the web interface.

Note

  • On Sympa 6.2.60 or earlier, the file named blacklist.txt was used for this implicit rule, and the name of corresponding parameter was use_blacklist.

spam-status special scenario

The scenario spam_status.x-spam-status determines whether an incoming message is tagged as SPAM.

Note

As of 6.2.72, pre-prepared scenarios for some spam filtering software are shipped. See the description on spam_status parameter.

You can use the result in your send scenarios, common use cases are below.

Reject the message:

equal([msg->spam_status],'spam')  smtp,md5,smime -> reject,quiet

Force moderation:

equal([msg->spam_status],'spam')  smtp,md5,smime -> editorkey,quiet

Hiding scenario files

Because Sympa is distributed with many default scenario files, you may want to hide some of them to list owners (to make list administration menus shorter and readable). To hide a scenario file, you should create an empty file with the :ignore suffix. Depending on where this file has been created, it will make it be ignored at either a global, domain or list level.

Example:

By creating $SYSCONFDIR/mail.example.org/scenari/send.public_nobcc:ignore, the public_nobcc send scenario will be hidden (on the web admin interface), at the mail.example.org domain level only.

Top of Page