= Blueprint for Authentication, Authorization & Accounting =

'''Authentication''' is the act of establishing or confirming someone's identity.[[BR]]
'''Authorization''' is the concept of allowing access to resources only to those permitted to use them.[[BR]]
'''Accounting''' refers to the tracking of user actions - an audit trail.

== Authentication ==
!SahanaPy currently authenticates on email address/password.[[BR]]
- this is the method supported by default in Web2Py (Auth class in {{{gluon/tools.py}}}).

The default configuration is that Self-Registration is enabled.[[BR]]
This can be easily disabled via a single setting in the s3_setting table.

The email address is currently not verified.[[BR]]
- this should be fixed. Web2Py supports this: {{{auth.settings.mailer=mail}}}

Web2Py also supports [http://recaptcha.net Recaptcha].

Sahana2 supports OpenID (as does Launchpad), so that would be good to support & looks easy:
 * http://openidenabled.com/python-openid/

== Authorization ==
We want to be able to provide a simple way of setting the overall security policy - allowing for flexible deployment options.
 * Anonymous access is granted for all Read operations, with Create/Update/Delete requiring a user to be Authenticated
 * Anonymous access isn't granted for anything - all access requires a user to be Authenticated
 * Modules able to be restricted by Role membership
 * Tables able to be restricted by Role membership
  * C/R/U/D permissions distinct
 * Records able to be restricted by Role membership
  * C/R/U/D permissions distinct

Sahana2 specifications:
 * Proposed Trunk: http://wiki.sahana.lk/doku.php?id=dev:new_acl
 * Current Stable: http://wiki.sahana.lk/doku.php?id=dev:security
 * Old: http://wiki.sahana.lk/doku.php?id=dev:authorization
(NB The Vol module currently uses a separate method)

We also want to look at whether we should link the {{{auth_user}}} table with the [BluePrintPersonRegistry Person Registry]'s person table

The admin role is pre-defined during initialisation in {{{_db.py}}} (The first user to register will have this role by default):
{{{
table = 'auth_group'
# 1st-run initialisation
if not len(db().select(db[table].ALL)):
    auth.add_group('Administrator',description='System Administrator - can access & make changes to any data')
    # 1st person created will be System Administrator (can be changed later)
    auth.add_membership(1,1)
}}}

Additional roles such as Country/Regional Admin, Organisation/Office/Camp Admin are set within the GIS/OR/CR modules respectively.

=== Implementation ===
S3 builds on the default Web2Py Auth system (in {{{gluon/tools.py}}}):
 * DeveloperGuidelinesAuthenticationAccess

Anonymous access is currently granted for all Read operations, with Create/Update/Delete requiring a user to be Authenticated: {{{auth.is_logged_in()}}}
 * Web2Py can extend this by protecting resources with {{{auth.has_membership()}}} (table level security which can be separated for C/R/U/D) & {{{auth.has_permission()}}} (record-level security)
 * we should probably support these by adding hooks into the [wiki:BluePrintREST RESTlike controller]

We use {{{sahana_group}}} table for Roles & {{{sahana_membership}}} to show which roles a user has.
 * admin role initialised in {{{_db.py}}}
 * 1st user to register gets Administrator role

We expose this as s3.roles so that it is accessible to Controllers & Views.[[BR]]
e.g.
 * {{{appadmin.py}}}
 * {{{layout.html}}}

User maintenance can be done via appadmin until we develop our own UI:
 * ConfigurationGuidelines#Roles

=== Links ===
 * J2EE: Working with Realms, Users, Groups, and Roles: http://java.sun.com/javaee/5/docs/tutorial/doc/bnbxj.html
 * Wikipedia: http://en.wikipedia.org/wiki/AAA_protocol
 * Zope uses: {{{has_permission(permission_name, view_or_controller)}}} and/or {{{user.has_role(custom_role)}}} methods

== Accounting ==
STATUS: Complete apart from needing to get new_values back from the form after processing.[[BR]]
The solution hooks the [wiki:BluePrintREST RESTlike controller] so anything which bypasses that is not logged (unless using the T2 fields: {{{created_by}}}, {{{updated_by}}}).[[BR]]

To do more would require patching the DAL.

Events can be audited at the Global level or the per-Module level.

Most auditing wins, so if the Global is True, then all Modules will Log. If Global is False then Modules have control & can selectively enable it.

Global settings are defined in {{{s3_settings}}} table.[[BR]]
Per-Module settings are defined in {{{module_settings}}} table.[[BR]]
Each defines 2 levels of Auditing - Audit just Changes (C/U/D), or also Reads:
  * {{{audit_read}}}
  * {{{audit_write}}}

These are passed to the session for use in controllers/displays:
  * {{{session.s3.audit_read}}}
  * {{{session.s3.audit_write}}}

For now this is configured via appadmin, although we should later make a nicer UI which has a single checkbox for 'Enable Auditing'.
This then opens up a two checkboxes:
 * Global
 * Module-specific

If each is ticked, this sets the {{{audit_write}}} & opens up an extra checkbox for 'Enable Auditing of Reads' (sets {{{audit_read}}}).

NB Web2Py's Auth now includes it's own auth_events table with granular logging options, so we may wish to make use of this.

We also have a bug whereby creations from listadd forms aren't getting recorded!

----
BluePrints