group Module

Jan Janak

   FhG FOKUS

Edited by

Jan Janak

   Copyright  2003 FhG FOKUS
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview

              1.1.1. Strict membership checking
              1.1.2. Regular Expression based checking

        1.2. Dependencies

              1.2.1. OpenSER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_url (string)
              1.3.2. table (string)
              1.3.3. user_column (string)
              1.3.4. domain_column (string)
              1.3.5. group_column (string)
              1.3.6. use_domain (integer)
              1.3.7. re_table (string)
              1.3.8. re_exp_column (string)
              1.3.9. re_gid_column (string)
              1.3.10. multiple_gid (integer)

        1.4. Exported Functions

              1.4.1. is_user_in(URI, group)
              1.4.2. get_user_group(URI, AVP)

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set db_url parameter
   1-2. Set table parameter
   1-3. Set user_column parameter
   1-4. Set domain_column parameter
   1-5. Set group_column parameter
   1-6. Set use_domain parameter
   1-7. Set re_table parameter
   1-8. Set reg_exp_column parameter
   1-9. Set re_gid_column parameter
   1-10. Set multiple_gid parameter
   1-11. is_user_in usage
   1-12. get_user_group usage
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   This module provides functionalities for different methods of
   group membership checking.
     _________________________________________________________

1.1.1. Strict membership checking

   There is a database table that contains list of users and
   groups they belong to. The module provides the possibility to
   check if a specific user belongs to a specific group.

   There is no DB caching support, each check involving a DB
   query.
     _________________________________________________________

1.1.2. Regular Expression based checking

   Another database table contains list of regular expressions
   and group IDs. A matching occurs if the user URI match the
   regular expression. This type of matching may be used to fetch
   the group ID(s) the user belongs to (via RE matching) .

   Due performance reasons (regular expression evaluation), DB
   cache support is available: the table content is loaded into
   memory at startup and all regular expressions are compiled.
     _________________________________________________________

1.2. Dependencies

1.2.1. OpenSER Modules

   The following modules must be loaded before this module:

     * A database module, like mysql, postgres or dbtext
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * None.
     _________________________________________________________

1.3. Exported Parameters

1.3.1. db_url (string)

   URL of the database table to be used.

   Default value is
   "mysql://openserro:openserro@localhost/openser". 

   Example 1-1. Set db_url parameter
...
modparam("group", "db_url", "mysql://username:password@dbhost/openser")
...
     _________________________________________________________

1.3.2. table (string)

   Name of the table holding strict definitions of groups and
   their members.

   Default value is "grp". 

   Example 1-2. Set table parameter
...
modparam("group", "table", "grp_table")
...
     _________________________________________________________

1.3.3. user_column (string)

   Name of the "table" column holding usernames.

   Default value is "username". 

   Example 1-3. Set user_column parameter
...
modparam("group", "user_column", "user")
...
     _________________________________________________________

1.3.4. domain_column (string)

   Name of the "table" column holding domains.

   Default value is "domain". 

   Example 1-4. Set domain_column parameter
...
modparam("group", "domain_column", "realm")
...
     _________________________________________________________

1.3.5. group_column (string)

   Name of the "table" column holding groups.

   Default value is "grp". 

   Example 1-5. Set group_column parameter
...
modparam("group", "group_column", "grp")
...
     _________________________________________________________

1.3.6. use_domain (integer)

   If enabled (set to non zero value) then domain will be used
   also used for strict group matching; otherwise only the
   username part will be used.

   Default value is 0 (no). 

   Example 1-6. Set use_domain parameter
...
modparam("group", "use_domain", 1)
...
     _________________________________________________________

1.3.7. re_table (string)

   Name of the table holding definitions for regular-expression
   based groups. If no table is defined, the regular-expression
   support is disabled.

   Default value is "NULL". 

   Example 1-7. Set re_table parameter
...
modparam("group", "re_table", "re_grp")
...
     _________________________________________________________

1.3.8. re_exp_column (string)

   Name of the "re_table" column holding the regular expression
   used for user matching.

   Default value is "reg_exp". 

   Example 1-8. Set reg_exp_column parameter
...
modparam("group", "reg_exp_column", "re")
...
     _________________________________________________________

1.3.9. re_gid_column (string)

   Name of the "re_table" column holding the group IDs.

   Default value is "group_id". 

   Example 1-9. Set re_gid_column parameter
...
modparam("group", "re_gid_column", "grp_id")
...
     _________________________________________________________

1.3.10. multiple_gid (integer)

   If enabled (non zero value) the regular-expression matching
   will return all group IDs that match the user; otherwise only
   the first will be returned.

   Default value is "1". 

   Example 1-10. Set multiple_gid parameter
...
modparam("group", "multiple_gid", 0)
...
     _________________________________________________________

1.4. Exported Functions

1.4.1. is_user_in(URI, group)

   This function is to be used for script group membership. The
   function returns true if username in the given URI is member
   of the given group and false if not.

   Meaning of the parameters is as follows:

     * URI - URI whose username and optionally domain to be used,
       this can be one of:
          + Request-URI - Use Request-URI username and
            (optionally) domain.
          + To - Use To username and (optionally) domain.
          + From - Use From username and (optionally) domain.
          + Credentials - Use digest credentials username.
          + $avp[avp_name|avp_alias] - Use the URI from the AVP
            specified by this pseudo-variable.
     * group - Name of the group to check.

   This function can be used from REQUEST_ROUTE and
   FAILURE_ROUTE.

   Example 1-11. is_user_in usage
...
if (is_user_in("Request-URI", "ld")) {
        ...
};
...
     _________________________________________________________

1.4.2. get_user_group(URI, AVP)

   This function is to be used for regular expression based group
   membership. The function returns true if username in the given
   URI belongs to at least on group; the group ID(s) are returned
   as AVPs.

   Meaning of the parameters is as follows:

     * URI - URI to be matched against the regular expressions:
          + Request-URI - Use Request-URI
          + To - Use To URI.
          + From - Use From URI
          + Credentials - Use digest credentials username and
            realm.
          + $avp[avp_name|avp_alias] - Use the URI from the AVP
            specified by this pseudo-variable.
     * AVP_ID - The matched group IDs are returned as AVPs named
       "AVP". It accepts a full AVP specification: AVP, ID and
       NAME. alias also

   This function can be used from REQUEST_ROUTE and
   FAILURE_ROUTE.

   Example 1-12. get_user_group usage
...
if (get_user_group("Request-URI", "i:10")) {
    xgdb("User $ru belongs to $avp(i:10[*]) group(s)\n");
    ....
};
...
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.