Homec4science
Diffusion invenio-infoscience (maint-1.0) Browse

R3600/modules/webaccess/doc/hacking/webaccess-firerole-api.webdoc
d30e56fa001amaint-1.0

Last Change
Raw File

webaccess-firerole-api.webdoc
View Options

## -*- mode: html; coding: utf-8; -*-
## This file is part of Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 CERN.
##
## Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: FireRole Internals -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/hacking">Hacking Invenio</a> &gt; <a class="navtrail" href="webaccess-internals">WebAccess Internals</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->
<pre>
The "Firewall like role definition engine" (FireRole) is a tool for describing
formally sets of users and checking users against this description for their membership.
FireRole rules are strings defined as in the <a href="webaccess-admin-guide#6">FireRole language description</a> page.
In order to use FireRole rules with the engine you have to compile these strings with
the <strong>compile_role_definition</strong> function.
The compiled form could be serialized and stored into a database with the provided
function <strong>serialize</strong> and later loaded with <strong>deserialize</strong>.
To build a user description you have to use the <strong>collect_user_info</strong> from
the module <em>webuser</em>. This function, given a <em>mod_python request object</em>
or a <em>id_user</em> returns a dictionary with all the collectable user informations (when
using the request object these includes the <em>ip address</em> and the <em>host</em>
of the user, too).
Passing both the user_info dictionary and the compiled (deserialized) FireRole
definition to the <strong>acc_firerole_check_user</strong> function returns a
<em>boolean value</em> stating if the user belong to the set described by this
definition.
FireRole definitions are integrated with <em>accROLEs</em>, in fact, you can pass
a uid, a req_object or user_info a dictionary to <strong>acc_authorize_action</strong>.
If necessary collect_user_info will be implicitly called, and user authorizations
will be checked first against direct traditional uid membership and then against
FireRole definitions.
<H2>API</H2>
<em>from webuser</em>
def <strong>collect_user_info</strong>(req):
"""Given the mod_python request object rec or a uid it returns a dictionary
containing at least the keys uid, nickname, email, groups, plus any external keys in
the user preferences (collected at login time and built by the different
external authentication plugins) and if the mod_python request object is
provided, also the remote_ip and remote_host fields.
"""
<em>from access_control_firerole</em>
def <strong>compile_role_definition</strong>(FireRole_def_src):
""" Given a text in which every row contains a rule it returns the compiled
object definition.
Rules have the following syntax:
allow|deny [not] field {list of one or more (double)quoted string or regexp}
or allow|deny any
Every row may contain a # sign followed by a comment which are discarded.
Field could be any key contained in a user_info dictionary. If the key does
not exist in the dictionary, the rule is skipped.
The first rule which matches return.
"""
def <strong>serialize</strong>(FireRole_def_obj):
""" Serialize and compress a definition."""
def <strong>deserialize</strong>(FireRole_def_ser):
""" Deserialize and decompress a definition."""
def <strong>acc_firerole_check_user</strong>(user_info, firerole_def_obj):
""" Given a user_info dictionary, it matches the rules inside the deserializez
compiled definition in order to discover if the current user match the roles
corresponding to this definition.
@param user_info a dict produced by collect_user_info which contains every
info about a user
@param firerole_def_obj a compiled deserialized definition produced by
compile_role_defintion
@return True if the user match the definition, False otherwise.
"""
</pre>
c4science · Help