next up previous contents index
Next: 15. virtual host Up: Sympa Mailing Lists Management Software version Previous: 13. Authentication   Contents   Index

Subsections


14. Authorization scenarios

List parameters controlling the behavior of commands are linked to different authorization scenarios. For example : the send private parameter is related to the send.private scenario. There are four possible locations for a authorization scenario. When Sympa seeks to apply an authorization scenario, it looks first in the related list directory /home/sympa/expl/<list>/scenari. If it does not find the file there, it scans the current robot configuration directory /home/sympa/etc/my.domain.org/scenari, then the site's configuration directory /home/sympa/etc/scenari, and finally /home/sympa/bin/etc/scenari, which is the directory installed by the Makefile.

An authorization scenario is a small configuration language to describe who can perform an operation and which authentication method is requested for it. An authorization scenario is an ordered set of rules. The goal is to provide a simple and flexible way to configure authorization and required authentication method for each operation.

Each authorization scenario rule contains :

Example

del.auth
title.us deletion performed only by list owners, need authentication
title.fr suppression r\'eserv\'ee au propri\'etaire avec authentification
title.es eliminacin reservada slo para el propietario, necesita autentificacin


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


14.1 rules specifications

An authorization scenario consists of rules, evaluated in order beginning with the first. Rules are defined as follows :

<rule> ::= <condition> <auth_list> -> <action>

<condition> ::= [!] <condition
                | true ()
                | all ()
                | equal (<var>, <var>)
                | match (<var>, /perl_regexp/)
		| search (<named_filter_file>)
                | is_subscriber (<listname>, <var>)
                | is_owner (<listname>, <var>)
                | is_editor (<listname>, <var>)
                | is_listmaster (<var>)
                | older (<date>, <date>)    # true if first date is anterior to the second date
                | newer (<date>, <date>)    # true if first date is posterior to the second date
                | CustomCondition::<package_name> (<var>*)

<var> ::= [email] | [sender] | [user-><user_key_word>] | [previous_email]
                  | [remote_host] | [remote_addr] | [user_attributes-><user_attributes_keyword>]
	 	  | [subscriber-><subscriber_key_word>] | [list-><list_key_word>] | [env-><env_var>]
		  | [conf-><conf_key_word>] | [msg_header-><smtp_key_word>] | [msg_body] 
	 	  | [msg_part->type] | [msg_part->body] | [msg_encrypted] | [is_bcc] | [current_date] 
		  | [topic-auto] | [topic-sender,] | [topic-editor] | [topic] | [topic-needed]
		  | <string>

[is_bcc] ::= set to 1 if the list is neither in To: nor Cc:

[sender] ::= email address of the current user (used on web or mail interface). Default value is 'nobody'

[previous_email] ::= old email when changing subscription email in preference page. 

[msg_encrypted] ::= set to 'smime' if the message was S/MIME encrypted

[topic-auto] ::= topic of the message if it has been automatically tagged

[topic-sender] ::= topic of the message if it has been tagged by sender

[topic-editor] ::= topic of the message if it has been tagged by editor

[topic]  ::= topic of the message

[topic-needed] ::= the message has not got any topic and message topic are required for the list

/perl_regexp/ ::= a perl regular expression. Don't forget to escape special characters (^, $, \{, \(, ...) 
Check http://perldoc.perl.org/perlre.html for regular expression syntax.

<date> ::= '<date_element> [ +|- <date_element>]'

<date_element> ::= <epoch_date> | <var> | <date_expr>

<epoch_date> ::= <integer>

<date_expr> ::= <integer>y<integer>m<integer>d<integer>h<integer>min<integer>sec

<listname> ::= [listname] | <listname_string>

<auth_list> ::= <auth>,<auth_list> | <auth>

<auth> ::= smtp|md5|smime

<action> ::=   do_it [,notify]
             | do_it [,quiet]
	     | reject(reason=<reason_key>) [,quiet]
	     | reject(tt2=<tpl_name>) [,quiet]
             | request_auth
             | owner
	     | editor
	     | editorkey[,quiet]
	     | listmaster

<reason_key> ::= match a key in mail_tt2/authorization_reject.tt2 template corresponding to 
                 an information message about the reason of the reject of the user
  
<tpl_name> ::= corresponding template (<tpl_name>.tt2) is send to the sender

<user_key_word> ::= email | gecos | lang | password | cookie_delay_user
	            | <additional_user_fields>

<user_attributes_key_word> ::= one of the user attributes provided by the SSO system via environment variables. The [user_attributes] structure is available only if user authenticated with a generic_sso.

<subscriber_key_word> ::= email | gecos | bounce | reception 
	                  | visibility | date | update_date
			  | <additional_subscriber_fields>

<list_key_word> ::= name | host | lang | max_size | priority | reply_to | 
		    status | subject | account | total

<conf_key_word> ::= domain | email | listmaster | default_list_priority | 
		      sympa_priority | request_priority | lang | max_size

<named_filter_file> ::= filename ending with .ldap , .sql or .txt

<package_name> ::= name of a perl package in /etc/custom_conditions/ (small letters)

(Refer to 17.8, page [*] for date format definition)

The function to evaluate scenario is described in section 29.2.6, page [*].

perl_regexp can contain the string [host] (interpreted at run time as the list or robot domain). The variable notation [msg_header-><smtp_key_word>] is interpreted as the SMTP header value only when evaluating the authorization scenario for sending messages. It can be used, for example, to require editor validation for multipart messages. [msg_part->type] and [msg_part->body] are the MIME parts content-types and bodies ; the body is available for MIME parts in text/xxx format only.

The difference between editor and editorkey is, that with editor the message is simply forwarded to the moderaotr. He then can forward it to the list, if he wishes. editorkey assigns a key to the message and sends it to the moderator together with the message. So the moderator can just send back the key to distribute the message. Please note, that moderation from the webinterface is only possible when using editorkey, because otherwise there is no copy of the message saved on the server.

A bunch of authorization scenarios is provided with the Sympa distribution ; they provide a large set of configuration that allow to create lists for most usage. But you will probably create authorization scenarios for your own need. In this case, don't forget to restart Sympa and wwsympa because authorization scenarios are not reloaded dynamicaly.

These standard authorization scenarios are located in the /home/sympa/bin/etc/scenari/ directory. Default scenarios are named <command>.default.

You may also define and name your own authorization scenarios. Store them in the /home/sympa/etc/scenari directory. They will not be overwritten by Sympa release. Scenarios can also be defined for a particular virtual host (using directory /home/sympa/etc/<robot>/scenari) or for a list ( /home/sympa/expl/<robot>/<list>/scenari ). Sympa will not dynamically detect that a list config should be reloaded after a scenario has been changed on disk.

Example:

Copy the previous scenario to scenari/subscribe.rennes1 :

equal([sender], 'userxxx@univ-rennes1.fr') smtp,smime -> reject
match([sender], /univ-rennes1\.fr$/) smtp,smime -> do_it
true()                               smtp,smime -> owner

You may now refer to this authorization scenario in any list configuration file, for example :

subscribe rennes1


14.2 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 realise some actions.

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

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

14.2.1 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 /home/sympa/etc/search_filters/.

You must give several informations in order to create a LDAP Named Filter:

example.ldap : we want to select the professors of mathematics in the university of Rennes1 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

14.2.2 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 /home/sympa/etc/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 7.10, page [*] 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 professors of mathematics in the university of Rennes1 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'

14.2.3 Search Condition

The search condition is used in authorization scenarios which are defined and described in (see 14)

The syntax of this rule is:

	search(example.ldap)      smtp,smime,md5    -> do_it
	search(blacklist.txt)     smtp,smime,md5    -> 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 1 hour in the cache.

When using .txt file extention, the file is read looking for a line that match the second parameter (usually the user email address). Each line is a string where the char * can be used once to mach any block. This feature is used by the blacklist implicit scenario rule. (see [*])

The method of authentication does not change.

14.3 scenario inclusion

Scenarios can also contain includes :

    subscribe
        include commonreject
        match(, /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.

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.

14.4 blacklist implicit rule

For each service listed in parameter use_blacklist (see 7.4.4), the following implicit scenario rule is added at the beginning of the scenario :

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

The goal is to block message or other service request from unwanted users. The blacklist can be defined for the robot or for the list. The one at the list level is to managed by list owner or list editor via the web interface.

14.5 Custom perl package conditions

You can use a perl package of your own to evaluate a custom condition. It could be usefull if you have very complex tasks to accomplish to evaluate your condition (web services queries...). You write a perl module, place it in the CustomCondition namespace, with one verify fonction that have to return 1 to grant access, undef to throw an error, or anything else to refuse the authorization.

This perl module:

For example, lets write the smallest custom condition that always returns 1.

  /home/sympa/etc/custom_conditions/yes.pm :

      #!/usr/bin/perl

      package CustomCondition::yes;

      use strict;
      use Log; # optional : we log parameters

      sub verify {
        my @args = @_;
        foreach my $arg (@args) {
          do_log ('debug3', 'arg: %s', $arg);
        }
        # I always say 'yes'
        return 1;
      }
      ## Packages must return true.
      1;

We can use this custom condition that way :

CustomCondition::yes(,,)      smtp,smime,md5    -> do_it
true()                               smtp,smime -> reject

Note that the ,, are optionnal, but it's the way you can pass information to your package. Our yes.pm will print their values in the logs.

Remember that the package name has to be small letters, but the 'CustomCondition' namespace is case sensitive. If your package return undef, the sender will receive an 'internal error' mail. If it returns anything else but '1', the sender will receive a 'forbidden' error.

14.6 Hidding scenario files

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

Example :

/home/sympa/etc/my.domain.org/scenari/send.intranetorprivate:ignore

The intranetorprivate send scenario will be hidden (on the web admin interface), at the my.domain.orgrobot level only.


next up previous contents index
Next: 15. virtual host Up: Sympa Mailing Lists Management Software version Previous: 13. Authentication   Contents   Index
root 2006-11-06