Diffusion invenio-infoscience (master) Browse

webaccess-admin-guide.webdoc
578eb774d9c7master

webaccess-admin-guide.webdoc
View Options

			## -- mode: html; coding: utf-8; --
			## This file is part of Invenio.
			## Copyright (C) 2007, 2008, 2009, 2010, 2011 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: WebAccess Admin Guide -->
			<!-- WebDoc-Page-Navbar-Select: webaccess-admin-guide -->
			<!-- WebDoc-Page-Revision: $Id$ -->

			<h2>Contents</h2>

			<strong>1. <a href="#1">Introduction, using roles</a></strong><br />
			<strong>2. <a href="#2">WebAccess admin interface</a></strong><br />
			<strong>3. <a href="#3">Example pages, illustrating snapshots</a></strong><br />
			<strong>4. <a href="#4">Managing accounts / Access policy</a></strong><br />
			<strong>5. <a href="#5">Managing login methods</a></strong><br />
			<strong>6. <a href="#6">Firewall-like role definitions</a></strong><br />

			<h2><a name="1">1. INTRODUCTION, USING ROLES</a></h2>
			<pre>
			WebAccess is a common RBAC, role based access control, for all of
			Invenio. This means that users are connected to roles that cover
			different areas of access. I.e <em>administrator of the photo
			collection</em> or <em>system librarian</em>. Users can be active in
			different areas and of course connected to as many roles as needed.

			The roles are connected to actions. An action identifies a task you
			can perform in Invenio. It can be defined to take any number of
			arguments in order to more clearly describe what you are allowing
			connected users to do.

			For example the system librarian can be allowed to run bibindex on
			the different indexes. To allow system librarians to run the
			bibindex indexing on the field author we connect role <em>system
			librarian</em> with action <em>runbibindex</em> using the argument
			<em>index='author'</em>.

			Additionally, roles could have <em><a href="#6">firewall-like role
			definitions</a></em>. A definition is a formal description of which
			users are entitled to belong to the role. So you have two ways for
			connecting users to roles. Either linking explicitly a user with the
			role or describing the characteristics that makes users belong to
			the role.

			WebAccess is based on allowing users to perform actions. This means
			that only allowed actions are stored in the access control engine's
			database.
			</pre>

			<h2><a name="2">2. WEBACCESS ADMIN INTERFACE</a></h2>
			<pre>
			All the WebAccess Administration web pages have certain
			features/design choices in common

			- Divided into steps

			The process of adding new authorizations/information is
			stepwise. The subtitle contains information about wich step you are
			on and what you are supposed to do.

			- Restart from any wanted step

			You can always start from an earlier step by simply clicking the
			wanted button. This is not a way to undo changes! No information
			about previous database is kept, so all changes are definite.

			- Change or new entry must confirmed

			On all the pages you will be asked to confirm the change, with
			information about what kind of change you are about to perform.

			- Links to other relevant admin areas on the right side

			To make it easier to perform your administration tasks, we have
			added a menu area on the right hand side of these pages. The menu
			contain links to other relevant admin pages and change according to
			the page you are on and the information you have selected.
			</pre>

			<h2><a name="3">3. EXAMPLE PAGES</a></h2>
			<pre>
			I. Role area
			II. Example - connecting role and user


			I. Role area</a>

			Administration tasks starts in one of the administration areas. The
			role area is the main area from where you can perform all your
			managing tasks. The other admin areas are just other ways of
			entering.

			</pre>

			<div class="snapshot">
			<table class="navtrailbox">
			<tr>
			<td class="navtrailboxbody">
			<a href="" class="navtrail">Home</a> > <a class=navtrail href="">Admin Area</a> > <a class=navtrail href="">WebAccess Admin</a> > <a class=navtrail href="">Manage WebAccess</a> > Role Administration
			</td>
			</tr>
			</table>
			<!-- end replaced page header -->

			<div class="pagebody">
			<div class="pagebodystripeleft">
			<div class="pageboxlefttop">
			</div>
			<div class="pageboxlefttopadd"></div>
			<div class="pageboxleftbottomadd"></div>
			<div class="pageboxleftbottom">
			</div>
			</div>
			<div class="pagebodystriperight">
			<div class="pageboxrighttop">
			</div>
			<div class="pageboxrighttopadd"></div>
			<div class="pageboxrightbottomadd"></div>
			<div class="pageboxrightbottom">
			</div>
			</div>
			<div class="pagebodystripemiddle">

			<h1 class="headline">Role Administration</h1>

			<table class="admin_wvar" width="95%">

			<thead>
			<tr>
			<th class="adminheaderleft" colspan="2">administration with roles as access point</th>
			</tr>
			</thead>
			<tbody>
			<tr>

			<td style="vertical-align: top; margin-top: 5px; width: 75%;">

			<dl>
			<dt>Users:</dt>
			<dd>add or remove users from the access to a role and its priviliges.</dd>
			<dt>Authorizations/Actions:</dt>
			<dd>these terms means almost the same, but an authorization is a <br />
			connection between a role and an action (possibly) containing arguments.</dd>
			<dt>Roles:</dt>
			<dd>see all the information attached to a role and decide if you want to<br />delete it.</dd>
			</dl>
			<table class="admin_wvar_nomargin">
			<tr>
			<th class="adminheader">id</th>
			<th class="adminheader">name</th>
			<th class="adminheader">description</th>
			<th class="adminheader">definition</th>
			<th class="adminheader">users</th>
			<th class="adminheader">authorizations / actions</th>
			<th class="adminheader">role</th>
			<th class="adminheader"></th>
			<th class="adminheader"></th>

			</tr>
			<tr><td class="admintdleft">2</td>
			<td class="admintdleft">photoadmin</td>
			<td class="admintdleft">Photo collection administrator</td>
			<td class="admintdleft">None</td>
			<td class="admintdleft"><a href="">add</a> / <a href="">delete</a></td>
			<td class="admintdleft"><a href="">add</a> / <a href="">modify</a> / <a href="">remove</a></td>
			<td class="admintdleft"><a href="">modify</a> / <a href="">delete</a></td>
			<td class="admintdleft"><a href="">show details</a></td>
			<td rowspan="3" style="vertical-align: top">

			</td>
			</tr>
			<tr>
			<td class="admintdleft">1</td>
			<td class="admintdleft">superadmin</td>
			<td class="admintdleft">superuser with all rights</td>
			<td class="admintdleft">allow email /.*@cern.ch/</td>
			<td class="admintdleft"><a href="">add</a> / <a href="">delete</a></td>
			<td class="admintdleft"><a href="">add</a> / <a href="">modify</a> / <a href="">remove</a></td>
			<td class="admintdleft"><a href="">modify</a> / <a href="">delete</a></td>
			<td class="admintdleft"><a href="">show details</a></td>
			</tr>
			<tr>
			<td class="admintdleft">3</td>
			<td class="admintdleft">webaccessadmin</td>
			<td class="admintdleft">WebAccess administrator</td>
			<td class="admintdleft">allow nickname 'jekyll'</td>
			<td class="admintdleft"><a href="">add</a> / <a href="">delete</a></td>
			<td class="admintdleft"><a href="">add</a> / <a href="">modify</a> / <a href="">remove</a></td>
			<td class="admintdleft"><a href="">modify</a> / <a href="">delete</a></td>
			<td class="admintdleft"><a href="">show details</a></td>
			</tr>
			</table>

			</td>

			<td style="vertical-align: top; margin-top: 5px; width: 25%;">

			<dl>
			<dt><a href="">Create new role</a></dt>
			<dd>go here to add a new role.</dd>
			<dt><a href="">Create new action</a></dt>
			<dd>go here to add a new action.</dd>
			</dl>

			</td>
			</tr>

			</tbody>
			</table>

			</tbody>
			</table>
			</div>
			</div>
			</div>

			<pre>

			II. Example - connecting role and user</a>

			One of the important tasks that can be handled via the WebAccess Admin Web Interface
			is the delegation of access rights to users. This is done by connecting them to the
			different roles offered.

			The task is divided into 5 simple and comprehensive steps. Below follows the pages from
			the different steps with comments on the ongoing procedure.

			- step 1 - select a role

			You must first select the role you want to connect users to. All the available roles are
			listed alfabetically in a select box. Just find the wanted role and select it. Then click on
			the button saying "select role".

			If you start from the Role Area, this step is already done, and you start directly on step 2.

			</pre>

			<div class="snapshot">

			<table border="0" cellspacing="0" cellpadding="0" class="navtrailbox" width="100%" summary="">
			<tr>
			<td class="navtrailboxbody">
			<a class="navtrail" href="">Home</a> > <a class="navtrail" href="">Admin Area</a> > <a class="navtrail" href="">WebAccess Admin</a> >
			<a class="navtrail" href="">Manage WebAccess</a> > <a class="navtrail" href="">Role Administration</a> > Connect user to role
			</td>

			</tr>
			</table>

			<div class="pagebody">
			<table border="0" cellspacing="0" cellpadding="0" width="100%" summary="">
			<tr valign="top">
			<td class="pagebodystripemiddle" align="left">
			<h1 class="headline">Connect user to role </h1>
			<table class="admin_wvar" width="100%" summary="">
			<thead>
			<tr>
			<th class="adminheaderleft" colspan="2">step 1 - select a role</th>
			</tr>
			</thead>
			<tbody>
			<tr>
			<td style="vertical-align: top; margin-top: 5px; width: 75%;">
			<form action="" method="POST">
			<span class="adminlabel">1. select role</span>
			<select name="id_role" class="admin_w200">
			<option value="0">* select role *</option>
			<option value="2">photoadmin</option>
			<option value="9">submitter</option>
			<option value="1">superadmin</option>
			<option value="4">systemlibrarian</option>
			<option value="3">webaccessadmin</option>
			</select>
			<input class="adminbutton" type="submit" value="select role">
			</form>
			</td>
			<td style="vertical-align: top; margin-top: 5px; width: 25%;">
			<dl>
			<dt><a href="">Create new role</a></dt>
			<dd>go here to add a new role.</dd>
			</dl>
			</td>
			</tr>
			</tbody>
			</table>
			</td>
			<td class="pagebodystriperight" width="120" align="right" valign="top">
			</td>
			</tr>
			</table>
			</div>

			</div>

			<pre>

			- step 2 - search for users

			As you can see, the subtitle of the page has now changed. The subtitle always tells you
			which step you are on and what your current task is.

			There can be possibly thousands of users using your online library, therefore it is important
			to make it easier to identify the user you are looking for. Give part of, or the entire search
			string and all users with partly matching e-mails will be listed on the next step.

			You can also see that the right hand menu has changed. This area is always updated with links
			to related admin areas.

			</pre>

			<div class="snapshot">

			<table border="0" cellspacing="0" cellpadding="0" class="navtrailbox" width="100%" summary="">
			<tr>
			<td class="navtrailboxbody">
			<a class="navtrail" href="">Home</a> > <a class="navtrail" href="">Admin Area</a> > <a class="navtrail" href="">WebAccess Admin</a> >
			<a class="navtrail" href="">Manage WebAccess</a> > <a class="navtrail" href="">Role Administration</a> > Connect user to role
			</td>

			</tr>
			</table>

			<div class="pagebody">
			<table border="0" cellspacing="0" cellpadding="0" width="100%" summary="">
			<tr valign="top">
			<td class="pagebodystripemiddle" align="left">
			<h1 class="headline">Connect user to role </h1>
			<table class="admin_wvar" width="100%" summary="">
			<thead>
			<tr>
			<th class="adminheaderleft" colspan="2">step 2 - search for users</th>
			</tr>
			</thead>
			<tbody>
			<tr>
			<td style="vertical-align: top; margin-top: 5px; width: 75%;">
			<form action="" method="POST">
			<span class="adminlabel">1. select role</span>
			<select name="id_role" class="admin_w200">
			<option value="0">* select role *</option>
			<option value="2">photoadmin</option>
			<option value="9">submitter</option>
			<option value="1" selected="selected">superadmin</option>
			<option value="4">systemlibrarian</option>
			<option value="3">webaccessadmin</option>
			</select>
			<input class="adminbutton" type="submit" value="select role">
			</form>
			<form action="" method="POST">
			<table summary="">
			<tr>
			<td>
			<span class="adminlabel">2. search pattern </span>
			<input class="admin_wvar" type="text" name="email_user_pattern" value="">
			<input type="hidden" name="id_role" value="1">
			</td>
			<td style="vertical-align: bottom">
			<input class="adminbutton" type="submit" value="search for users">
			</td>
			</tr>
			</table>
			</form>
			</td>
			<td style="vertical-align: top; margin-top: 5px; width: 25%;">
			<dl>
			<dt><a href="">Create new role</a></dt>
			<dd>go here to add a new role.</dd>
			</dl>
			<dl>
			<dt><a href="">Remove users</a></dt>
			<dd>remove users from role superadmin.</dd>
			<dt><a href="">Connected users</a></dt>
			<dd>show all users connected to role superadmin.</dd>
			</dl>
			<dl>
			<dt><a href="">Add authorization</a></dt>
			<dd>start adding new authorizations to role superadmin.</dd>
			</dl>
			</td>
			</tr>
			</tbody>
			</table>
			</td>
			<td class="pagebodystriperight" width="120" align="right" valign="top">
			</td>
			</tr>
			</table>
			</div>

			</div>

			<pre>

			- step 3 - select a user.

			The select box contains all users with partly matching e-mail addresses. Select the one
			you want to connect to the role and continue.

			Notice the navigation trail that tells you were on the Administrator pages you are currently
			working.

			</pre>

			<div class="snapshot">

			<table border="0" cellspacing="0" cellpadding="0" class="navtrailbox" width="100%" summary="">
			<tr>
			<td class="navtrailboxbody">
			<a class="navtrail" href="">Home</a> > <a class="navtrail" href="">Admin Area</a> > <a class="navtrail" href="">WebAccess Admin</a> >
			<a class="navtrail" href="">Manage WebAccess</a> > <a class="navtrail" href="">Role Administration</a> > Connect user to role
			</td>

			</tr>
			</table>

			<div class="pagebody">
			<table border="0" cellspacing="0" cellpadding="0" width="100%" summary="">
			<tr valign="top">
			<td class="pagebodystripemiddle" align="left">
			<h1 class="headline">Connect user to role </h1>
			<table class="admin_wvar" width="100%" summary="">
			<thead>
			<tr>
			<th class="adminheaderleft" colspan="2">step 3 - select a user</th>
			</tr>
			</thead>
			<tbody>
			<tr>
			<td style="vertical-align: top; margin-top: 5px; width: 75%;">
			<form action="" method="POST">
			<span class="adminlabel">1. select role</span>
			<select name="id_role" class="admin_w200">
			<option value="0">* select role *</option>
			<option value="2">photoadmin</option>
			<option value="9">submitter</option>
			<option value="1" selected="selected">superadmin</option>
			<option value="4">systemlibrarian</option>
			<option value="3">webaccessadmin</option>
			</select>
			<input class="adminbutton" type="submit" value="select role">
			</form>

			<form action="" method="POST">
			<table summary="">
			<tr>
			<td>
			<span class="adminlabel">2. search pattern </span>
			<input class="admin_wvar" type="text" name="email_user_pattern" value="k">
			<input type="hidden" name="id_role" value="1">
			</td>
			<td style="vertical-align: bottom">
			<input class="adminbutton" type="submit" value="search for users">
			</td>
			</tr>
			</table>
			</form>

			<form action="" method="POST">
			<span class="adminlabel">3. select user</span>
			<select name="id_user" class="admin_w200">
			<option value="0">* select user *</option>
			<option value="136">franck.black@cern.ch</option>
			<option value="134">kurt.cobain@cern.ch</option>
			<option value="100" selected="selected">mikael.vik@cern.ch</option>
			<option value="-6">tibor.simko@cern.ch (connected)</option>
			</select>
			<input type="hidden" name="id_role" value="1">
			<input type="hidden" name="email_user_pattern" value="k">
			<input class="adminbutton" type="submit" value="add this user">
			</form>
			</td>
			<td style="vertical-align: top; margin-top: 5px; width: 25%;">
			<dl>
			<dt><a href="">Create new role</a></dt>
			<dd>go here to add a new role.</dd>
			</dl>
			<dl>
			<dt><a href="">Remove users</a></dt>
			<dd>remove users from role superadmin.</dd>
			<dt><a href="">Connected users</a></dt>
			<dd>show all users connected to role superadmin.</dd>
			</dl>
			<dl>
			<dt><a href="">Add authorization</a></dt>
			<dd>start adding new authorizations to role superadmin.</dd>
			</dl>
			</td>
			</tr>
			</tbody>
			</table>
			</td>
			<td class="pagebodystriperight" width="120" align="right" valign="top">
			</td>
			</tr>
			</table>
			</div>

			</div>

			<pre>

			- step 4 - confirm to add user

			All WebAccess Administrator web pages display the action you are about to peform, this
			means explaining what kind of addition, change or update will be done to your access control
			data.

			If you are happy with your decision, simply confirm it.

			</pre>

			<div class="snapshot">

			<table border="0" cellspacing="0" cellpadding="0" class="navtrailbox" width="100%" summary="">
			<tr>
			<td class="navtrailboxbody">
			<a class="navtrail" href="">Home</a> > <a class="navtrail" href="">Admin Area</a> > <a class="navtrail" href="">WebAccess Admin</a> >
			<a class="navtrail" href="">Manage WebAccess</a> > <a class="navtrail" href="">Role Administration</a> > Connect user to role
			</td>

			</tr>
			</table>

			<div class="pagebody">
			<table border="0" cellspacing="0" cellpadding="0" width="100%" summary="">
			<tr valign="top">
			<td class="pagebodystripemiddle" align="left">
			<h1 class="headline">Connect user to role </h1>
			<table class="admin_wvar" width="100%" summary="">
			<thead>
			<tr>
			<th class="adminheaderleft" colspan="2">step 4 - confirm to add user</th>
			</tr>
			</thead>
			<tbody>
			<tr>
			<td style="vertical-align: top; margin-top: 5px; width: 75%;">
			<form action="" method="POST">
			<span class="adminlabel">1. select role</span>
			<select name="id_role" class="admin_w200">
			<option value="0">* select role *</option>
			<option value="2">photoadmin</option>
			<option value="9">submitter</option>
			<option value="1" selected="selected">superadmin</option>
			<option value="4">systemlibrarian</option>
			<option value="3">webaccessadmin</option>
			</select>
			<input class="adminbutton" type="submit" value="select role">
			</form>

			<form action="" method="POST">
			<table summary="">
			<tr>
			<td>
			<span class="adminlabel">2. search pattern </span>
			<input class="admin_wvar" type="text" name="email_user_pattern" value="k">
			<input type="hidden" name="id_role" value="1">
			</td>
			<td style="vertical-align: bottom">
			<input class="adminbutton" type="submit" value="search for users">
			</td>
			</tr>
			</table>
			</form>

			<form action="" method="POST">
			<span class="adminlabel">3. select user</span>
			<select name="id_user" class="admin_w200">
			<option value="0">* select user *</option>
			<option value="136">franck.black@cern.ch</option>
			<option value="134">kurt.cobain@cern.ch</option>
			<option value="100" selected="selected">mikael.vik@cern.ch</option>
			<option value="-6">tibor.simko@cern.ch (connected)</option>
			</select>
			<input type="hidden" name="id_role" value="1">
			<input type="hidden" name="email_user_pattern" value="k">
			<input class="adminbutton" type="submit" value="add this user">
			</form>

			<form action="" method="POST">
			<table summary="">
			<tr>
			<td>add user <strong>mikael.vik@cern.ch</strong> to role <strong>superadmin</strong>?
			<input type="hidden" name="confirm" value="1">
			<input type="hidden" name="id_user" value="100">
			<input type="hidden" name="id_role" value="1">
			<input type="hidden" name="email_user_pattern" value="k">
			</td>
			<td style="vertical-align: bottom">
			<input class="adminbutton" type="submit" value="confirm" />
			</td>
			</tr>
			</table>
			</form>
			</td>
			<td style="vertical-align: top; margin-top: 5px; width: 25%;">
			<dl>
			<dt><a href="">Create new role</a></dt>
			<dd>go here to add a new role.</dd>
			</dl>
			<dl>
			<dt><a href="">Remove users</a></dt>
			<dd>remove users from role superadmin.</dd>
			<dt><a href="">Connected users</a></dt>
			<dd>show all users connected to role superadmin.</dd>
			</dl>
			<dl>
			<dt><a href="">Add authorization</a></dt>
			<dd>start adding new authorizations to role superadmin.</dd>
			</dl>
			</td>
			</tr>
			</tbody>
			</table>
			</td>
			<td class="pagebodystriperight" width="120" align="right" valign="top">
			</td>
			</tr>
			</table>
			</div>

			</div>

			<pre>

			- step 5 - confirm user added.

			The user has now been added to this role. You can easily continue adding more users to this
			role be restarting from step 2 or 3. You can also go directly to another area and keep working
			on the same role.

			</pre>

			<div class="snapshot">

			<table border="0" cellspacing="0" cellpadding="0" class="navtrailbox" width="100%" summary="">
			<tr>
			<td class="navtrailboxbody">
			<a class="navtrail" href="">Home</a> > <a class="navtrail" href="">Admin Area</a> > <a class="navtrail" href="">WebAccess Admin</a> >
			<a class="navtrail" href="">Manage WebAccess</a> > <a class="navtrail" href="">Role Administration</a> > Connect user to role
			</td>

			</tr>
			</table>

			<div class="pagebody">
			<table border="0" cellspacing="0" cellpadding="0" width="100%" summary="">
			<tr valign="top">
			<td class="pagebodystripemiddle" align="left">
			<h1 class="headline">Connect user to role </h1>
			<table class="admin_wvar" width="100%" summary="">
			<thead>
			<tr>
			<th class="adminheaderleft" colspan="2">step 5 - confirm user added</th>
			</tr>
			</thead>
			<tbody>
			<tr>
			<td style="vertical-align: top; margin-top: 5px; width: 75%;">
			<form action="" method="POST">
			<span class="adminlabel">1. select role</span>
			<select name="id_role" class="admin_w200">
			<option value="0">* select role *</option>
			<option value="2">photoadmin</option>
			<option value="9">submitter</option>
			<option value="1" selected="selected">superadmin</option>
			<option value="4">systemlibrarian</option>
			<option value="3">webaccessadmin</option>
			</select>
			<input class="adminbutton" type="submit" value="select role">
			</form>

			<form action="" method="POST">
			<table summary="">
			<tr>
			<td>
			<span class="adminlabel">2. search pattern </span>
			<input class="admin_wvar" type="text" name="email_user_pattern" value="k">
			<input type="hidden" name="id_role" value="1">
			</td>
			<td style="vertical-align: bottom">
			<input class="adminbutton" type="submit" value="search for users">
			</td>
			</tr>
			</table>
			</form>

			<form action="" method="POST">
			<span class="adminlabel">3. select user</span>
			<select name="id_user" class="admin_w200">
			<option value="0">* select user *</option>
			<option value="136">franck.black@cern.ch</option>
			<option value="134">kurt.cobain@cern.ch</option>
			<option value="100" selected="selected">mikael.vik@cern.ch</option>
			<option value="-6">tibor.simko@cern.ch (connected)</option>
			</select>
			<input type="hidden" name="id_role" value="1">
			<input type="hidden" name="email_user_pattern" value="k">
			<input class="adminbutton" type="submit" value="add this user">
			</form>

			<form action="" method="POST">
			<table summary="">
			<tr>
			<td>add user <strong>mikael.vik@cern.ch</strong> to role <strong>superadmin</strong>?
			<input type="hidden" name="confirm" value="1">
			<input type="hidden" name="id_user" value="100">
			<input type="hidden" name="id_role" value="1">
			<input type="hidden" name="email_user_pattern" value="k">
			</td>
			<td style="vertical-align: bottom">
			<input class="adminbutton" type="submit" value="confirm" />
			</td>
			</tr>
			</table>
			</form>

			<p>confirm: user <strong>mikael.vik@cern.ch</strong> added to role <strong>superadmin</strong>.</p>

			</td>
			<td style="vertical-align: top; margin-top: 5px; width: 25%;">
			<dl>
			<dt><a href="">Create new role</a></dt>
			<dd>go here to add a new role.</dd>
			</dl>
			<dl>
			<dt><a href="">Remove users</a></dt>
			<dd>remove users from role superadmin.</dd>
			<dt><a href="">Connected users</a></dt>
			<dd>show all users connected to role superadmin.</dd>
			</dl>
			<dl>
			<dt><a href="">Add authorization</a></dt>
			<dd>start adding new authorizations to role superadmin.</dd>
			</dl>
			</td>
			</tr>
			</tbody>
			</table>
			</td>
			<td class="pagebodystriperight" width="120" align="right" valign="top">
			</td>
			</tr>
			</table>
			</div>

			</div>

			<pre>

			- we are done

			This example is very similar to all the other pages where you administrate WebAccess. The pages
			are an easy gateway to maintaing access control rights and share a lot of features.
			- divided into steps
			- restart from any wanted step (not undo)
			- changes must be confirmed
			- link to other relevant areas
			- prevent unwanted input

			As an administrator with access to these pages you are free to manage the rights any way you want.
			</pre>

			<h2><a name="4">IV. Managing accounts and access policy</a></h2>
			<pre>
			Here you can administrate the accounts and the access policy for your Invenio installation.

			- Access policy:

			To change the access policy, the general config file (or
			access_control_config.py) must be edited manually in a text
			editor. The site can there be defined as opened or closed, you can
			edit the access policy level for guest accounts, registered
			accounts and decide when to warn the owner of the account when
			something happens with it, either when it is created, deleted or
			approved. The Apache server must be restarted after modifying
			these settings.

			The two levels for guest account, are:
			0 - Allow guest accounts
			1 - Do not allow guest accounts
			The five levels for normal accounts, are:
			0 - Allow user to create account, automatically activate new accounts
			1 - Allow user to create account, administrator must activate account
			2 - Only administrators can create account. User cannot edit the email address.
			3 - Users cannot register or update account information (email/password)
			4 - User cannot change default login method
			You can configure Invenio to send an email:
			1. To an admin email-address when an account is created
			2. To the owner of an account when it is created
			3. To the owner of an account when it is activated
			4. To the owner of an account when it is deleted

			Define how open the site is:
			0 = normal operation of the site
			1 = read-only site, all write operations temporarily closed
			2 = site fully closed
			3 = database connections disabled
			CFG_ACCESS_CONTROL_LEVEL_SITE = 0
			Access policy for guests:
			0 = Allow guests to search,
			1 = Guests cannot search (all users must login)
			CFG_ACCESS_CONTROL_LEVEL_GUESTS = 0
			Access policy for accounts:
			0 = Users can register, automatically acticate accounts
			1 = Users can register, but admin must activate the accounts
			2 = Users cannot register or change email address, only admin can register accounts.
			3 = Users cannot register or update email address or password, only admin can register accounts.
			4 = Same as 3, but user cannot change login method.
			CFG_ACCESS_CONTROL_LEVEL_ACCOUNTS = 0

			Limit email addresses available to use when register a new account (example: cern.ch):
			CFG_ACCESS_CONTROL_LIMIT_REGISTRATION_TO_DOMAIN = ""

			Send an email when a new account is created by an user:
			CFG_ACCESS_CONTROL_NOTIFY_ADMIN_ABOUT_NEW_ACCOUNTS = 0

			Send an email to the user notifying when the account is created:
			CFG_ACCESS_CONTROL_NOTIFY_USER_ABOUT_NEW_ACCOUNT = 0

			Send an email to the user notifying when the account is activated:
			CFG_ACCESS_CONTROL_NOTIFY_USER_ABOUT_ACTIVATION = 0

			Send an email to the user notifying when the account is deleted/rejected:
			CFG_ACCESS_CONTROL_NOTIFY_USER_ABOUT_DELETION = 0

			- Account overview:
			Here you find an overview of the number of guest accounts, registered accounts and accounts
			awaiting activation, with a link to the activation page.

			- Create account:
			For creating new accounts, the email address must be unique. If configured to do so, an email
			will be sent to the given address when an account is created.

			- Edit accounts:
			For activating or rejecting accounts in addition to modifying them. An activated account can be
			inactivated for a short period of time, but this will not warn the account owner. To find accounts
			enter a part of the email address of the account and then search. This may take some time. If there
			are more than the selected number of accounts per page, you can use the next/prev links to switch
			pages. The accounts to search in can also be limited to only activated or not activated accounts.

			- Edit account:
			When editing one account, you can change the email address, password, delete the account, or modify
			the baskets or alerts belonging to one account. Which login method should be the default for this
			account can also be selected. To modify baskets or alerts, you need to login as the user, and
			modify the desired data as a normal user. Remember to log out as the user when you are finished
			editing.
			Here you can also edit the user's REST API keys changing its status to the desired one. This status
			is specified by CFG_REST_API_KEY_STATUS (only the first three are mandatory):
			0 = OK
			1 = REMOVED
			2 = REVOKED
			3 = WARNING1
			4 = WARNING2
			5 = WARNING3

			</pre>

			<h2><a name="5">V. Managing login methods</a></h2>
			<pre>
			Invenio supports using external login systems to authenticate users.

			When a user wants to login, the username and password given by the user is checked against the selected
			system, if the user is authenticated by the external system, a valid email-address is returned to
			Invenio and used to recognize the user within Invenio.

			If a new user is trying to login without having an account, using an external login system, an account
			is automatically created in Invenio to recognize and store the users settings. The password for the
			local account is randomly generated.

			If you want the user to be unable to change login method and account username / password, forcing use
			of certain external systems, set <strong>CFG_ACCESS_CONTROL_LEVEL_ACCOUNTS</strong> to <em>4</em> as mentioned in the last paragraph.

			If a user is changing login method from an <em>external</em> one to the <em>internal</em>, he also need to either change the
			password before logging out, or set the password via the lost password email service.

			If you are using <strong>CFG_ACCESS_CONTROL_LEVEL_ACCOUNTS</strong> with a value greater than <em>1</em> note
			that, even if the first login of a user through an external authentication technically means registering
			the user into the system, this is not the semantic expected behaviour by the user. The user is already
			<em>registered</em> at an authority that we trust, so there's no need to prevent the user from being imported
			into the system. That's why for external authentication <strong>CFG_ACCESS_CONTROL_LEVEL_ACCOUNTS</strong> is not
			considered apart from what said above.

			If a external login system is used, you may want to protect the users username / password using <strong>HTTPS</strong>.

			To add new system, two changes must be made (for the time being):
			- The name of the method, if it is default or not, and an instance of the class must be added to the variable
			<strong>CFG_EXTERNAL_AUTHENTICATION</strong> in <em>access_control_config.py</em>.

			- A class must be created derived from the class external_authentication inside file
			<em>external_authentication.py</em>. This class must include at least the
			function <strong>auth_user</strong>. This function returns a valid email-address in <em>Invenio</em> if the user
			is authenticated, not necessarily the same entered by the user as username. If the user
			is not authenticated, return <em>None</em>.
			The class could also provide five more methods: <strong>fetch_user_preferences</strong>, <strong>user_exists</strong>,
			<strong>fetch_user_groups_membership</strong> and <strong>fetch_all_users_groups_membership</strong>.
			The first should take an email and eventually a password and should return a dictionary of keys
			and value representing external preferences, infos or settings. If, for some reasons, you like
			to force some kind of hiding for some particular field you should export the related key
			prefixed by <em>"HIDDEN_"</em>. Those fields won't be displayed in tables and pages regarding external
			settings.
			The second method should check through the external system if a particular email exists. If you
			provide such a method then a user will be able to switch from and to this authorization method.
			The third method should take an email and (if necessary) a password
			and should return a dictionary of external_groups_names toghether with their description, for which
			the user has a membership. Those groups will be merged into the groups system.
			The user will be a member of those groups and will be able to use them in any place
			where groups are useful, but won't be able to unsubscribe or to administrate them.
			The fourth method should just return a dictionary of external groups as keys and tuples containing
			a group description and a list of email of users belonging to each groups. Those memberships
			will be merged into the database in the way done by the previous method, but could
			provide batch synchronization of groups.
			The fifth method should just return the nickname as is known by the external authentication
			system, given the usual email/username and the password.
			Note: if your system has more than one external login methods then incoherence in the groups
			memberships could happen when a user switch his login method. This will be fixed some times in the
			future.
			If you add as an attribute of your class the <strong>enforce_external_nicknames</strong> and set it to <em>True</em>, this will enforce
			the system to import external nicknames whenever the user login with the external login method for the
			first time. Since a nickname is not changable this will stay fixed forever. If this nickname is
			already registered in the system (suppose that is linked with a local account) then it will not be
			imported. If this variable doesn't exist or is set to <em>False</em> then no nickname will be
			imported and the user will be free to choose a nickname in the future (and then this will again
			stay forever).
			Note: every method will receive as last parameter the <em>mod_python request object</em>, that could
			be used for particular purposes.


			Example template:
			from invenio.modules.access.external_authentication import ExternalAuth, InvenioWebAccessExternalAuthError

			class ExternalAuthFoo(ExternalAuth):
			"""External authentication template example."""

			def __init__ (self):
			"""Initialize stuff here."""
			self.name = None
			self.enforce_external_nicknames = False
			pass

			def auth_user(self, username, password, req=None):
			"""Authenticate user-supplied USERNAME and PASSWORD.
			Return None if authentication failed, or the email address of the
			person if the authentication was successful. In order to do
			this you may perhaps have to keep a translation table between
			usernames and email addresses.
			Raise InvenioWebAccessExternalAuthError in case of external troubles.
			"""
			raise NotImplementedError
			#return None

			def user_exists(self, email, req=None):
			"""Checks against external_authentication for existance of email.
			@return True if the user exists, False otherwise
			"""
			raise NotImplementedError

			def fetch_user_groups_membership(self, username, password=None, req=None):
			"""Given a username, returns a dictionary of groups
			and their description to which the user is subscribed.
			Raise InvenioWebAccessExternalAuthError in case of troubles.
			"""
			raise NotImplementedError
			#return {}

			def fetch_user_preferences(self, username, password=None, req=None):
			"""Given a username and a password, returns a dictionary of keys and
			values, corresponding to external infos and settings.

			userprefs = {"telephone": "2392489",
			"address": "10th Downing Street"}
			"""
			raise NotImplementedError
			#return {}

			def fetch_all_users_groups_membership(self, req=None):
			"""Fetch all the groups with a description, and users who belong to
			each groups.
			@return {'mygroup': ('description', ['email1', 'email2', ...]), ...}
			"""
			raise NotImplementedError

			def fetch_user_nickname(self, username, password, req=None):
			"""Given a username and a password, returns the right nickname belonging
			to that user (username could be an email).
			"""
			raise NotImplementedError
			#return Nickname
			</pre>

			<h2><a name="6">VI. FIREWALL-LIKE ROLE DEFINITIONS</a></h2>

			<strong>The FireRole language description</strong>

			<pre>
			In the WebAccess RBAC system, roles are built up from their names,
			description and definition.

			A definition is the way to <em>formally implicitly define</em> which users belong
			to which roles.

			A definition is expressed in a <em>firewall like rules language</em>. It's built up
			by rows which are matched from top to bottom, in order to decide if the
			current user (wethever he/she is logged in or not) may belong to a role.

			Any row has this syntax:

			<strong>ALLOW/DENY ANY/ALL</strong>

			<strong>ALLOW/DENY FROM/UNTIL <em>"YYYY-MM-DD"</em></strong>

			or

			<strong>ALLOW/DENY [NOT] <em>field</em> {<em>one or more values</em>}</strong>

			The rows are parsed from top to bottom. If a row matches the user than the
			user belongs to the role if the rule is an ALLOW rule, otherwise, if the
			rule is a DENY one, the user doesn't belong to the role.

			A rule of the kind ALLOW\|DENY ANY always matches, regardless of the user.

			Note, in place of ANY you can use the word ALL. The semantic is the same. The
			system support both to let the user comply with the English grammar.

			The second type of rule is interpreted as follows: given a date in the
			form <em>"YYYY-MM-DD"</em> (double-)quoted), the rule is matched if, when using <strong>FROM</strong>,
			the current date is either identical or <em>'bigger'</em> than the given date, or if,
			when using <strong>UNTIL</strong>, the current date is either identical or <em>'smaller'</em> than the
			given date. If the rule starts with <strong>ALLOW</strong> and is matched
			then the next row is evaluated. If it is not matched, then the whole FireRole
			will evaluate into a DENY ALL. If the rule starts with <strong>DENY</strong> and
			is matched then the whole FireRole while evaluate as a DENY ALL. If it is
			not matched then the next row is evaluated.

			The third type of rule is interpreted as follows: given a dictionary
			of keys:values describing a user (we will cover this below), the rule
			considers the value associated with the key named in field, and checks
			if it corresponds to at least one of the values in the "one or more values" list.
			This is a list of comma separated strings, which can be literal
			(double-)quoted strings or regexps (marked by `/' ... `/' signs). If at
			least a value matches (literally or through the regexp language), the
			whole rule is considered to match.
			If the optional NOT keyword is specified than if at least a value of the
			rule matches the rule is skipped, otherwise if all the value of the rules
			don't match the whole rule matches.

			A <strong>DENY ALL</strong> rule is implicitly added at the end of every definition. Note that
			this imply that, if you are using e.g. a temporal rule (FROM/UNTIL), you
			should explicitly add an additional row with value <strong>ALLOW ANY</strong>,
			if you actually want to allow users in the specified timeframe.

			Any field is valid, but only rules concerning fields which currently
			exist in the user describing dictionary are checked. All the rules
			with non existant fields are skipped.

			The user describing dictionary (user_info) is built at runtime with all the informations
			that can be gathered about the current user (and its session).
			Currently valid fields are: <em>uid, email, nickname, remote_ip,
			remote_host, groups</em> and all the external settings provided
			by the external authentication systems (e.g. CERN SSO provides:
			external_authmethod, external_building, external_department, external_email,
			external_external, external_firstname, external_fullname, external_homdir,
			external_homeinstitute, external_lastname, external_login, external_mobilenumber,
			external_phonenumber).

			Among those fields there are some special cases, which are <em>remote_ip</em> and
			(<em>apache_</em>)<em>groups</em>. Rules can refer to remote_ip either using a literal
			expression for specifing list of single ips, or a usual regexp (or list
			of regexps), or, also, using the common network group/mask notation
			(e.g. <em>"127.0.0.0/24"</em>) as a literal string, which is a mix between literal
			expressions and regexps. (apache_)groups are related to group memberships.
			Since a user will probably belong to more than a group, then the rule
			matches if there's at least one group to which the user belong, that matches
			at least one of the expressions (NOT rules behave as you can imagine).

			The dictionary is built using the current user session. If the user is
			authenticated in some way (apache, locally, externally, SSO...) then more
			infos could be provided to the firerole system in order to decide if the
			user should belong to a role or not.

			The default fields that are always there are:
			<ul>
			<li><strong>uid</strong>: an integer representing the user id</li>
			<li><strong>nickname</strong>: the nickname of the user</li>
			<li><strong>email</strong>: the email of the user</li>
			<li><strong>group/groups</strong>: local or external group to which the user belong</li>
			<li><strong>guest</strong>: 1 if the user is a guest (not logged), 0 otherwise</li>
			</ul>
			plus all the external setting retrieved by an <a href="webaccess-admin-guide#5">external authentication system</a>.

			If the action to which the role defined is raised from the webinterface of
			Invenio, then you will have those additional fields:
			<ul>
			<li><strong>remote_ip</strong>: the remote ip address of the user who is browsing</li>
			<li><strong>remote_host</strong>: the remote hostname of the user who is browsing</li>
			<li><strong>referer</strong>: the webpage from where the user is coming from</li>
			<li><strong>uri</strong>: the uri the user is visiting</li>
			<li><strong>agent</strong>: the agent string describing the user's browser</li>
			</ul>

			Note that you can specify either (apache_)group or (apache_)groups (with or
			without the trailing s). They are semantically equal and are supported just
			to let people comply with the English grammar.

			Every rule is <em>case-insensitive</em> (apart values which must match literally
			and regexp values which don't explicitly specify case-insesitive matches).

			Every rule may contain <em>comments</em> preceded by the '<em>#</em>' character.
			Any comment is discarded.

			When you set a definition for a role, it is actually compiled and stored
			in a binary compressed form inside the database. If the syntax isn't correct
			this will be stated and the definition won't be set or updated.

			Example of role definition:
			allow not email /.@gmail.com/,/.@hotmail.com/
			deny group badguys
			allow remote_ip "127.0.0.0/24"
			deny all

			This definition would match all users whose emails don't end with @gmail.com and
			@hotmail.com, or who don't belong to the group badguys and have remote_ip
			in the 24bit mask network of 127.0.0.0. All the the other users don't belong
			to the role which is being defined.

			If you want to discover which keys are available on your system to build a FireRole
			rule, just login with your account in your installation and visit <a href="<CFG_SITE_SECURE_URL>/youraccount/edit?verbose=9">your account page</a>,
			by activating verbose=9 variable. Under the tile you will se the available keys and
			values that you can use to build a FireRole rule. All but fields prefixed with
			<strong>precached_</strong> are usuable.
			</pre>

R3600/invenio/legacy/webaccess/admin/webaccess-admin-guide.webdoc578eb774d9c7master

webaccess-admin-guide.webdocView Options

R3600/invenio/legacy/webaccess/admin/webaccess-admin-guide.webdoc
578eb774d9c7master

webaccess-admin-guide.webdoc
View Options