= 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 can be verified:
{{{
auth.settings.registration_requires_verification = False
}}}

We can also use [http://recaptcha.net Recaptcha].

We can easily add support for OpenID (like Sahana2 & Launchpad):
 * Web2Py implementation: http://groups.google.com/group/web2py/browse_thread/thread/8d13546b902409a9
 * http://openidenabled.com/python-openid/
 * https://rpxnow.com/
  * Web2Py implementation that works alongside local users: http://www.web2pyslices.com/main/slices/take_slice/28

== 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

It should be possible to completely disable the ability to Delete records (instead they would be marked as 'Inactive'. Inactive records can be archived). This is for Audit purposes.[[BR]]
Marking as inactive should be done using a date field instead of a simple boolean since then records can be set to expire.

 * Example on populating dropdowns based on authorised records: http://groups.google.com/group/web2py/browse_thread/thread/42c6044b651e5dea#

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 {{{00_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

There are 3 modes for Authorisation right now:[[BR]]
 * simple:
  * Anonymous access is granted for all Read operations
  * Create/Update/Delete requires a user to be Authenticated
 * full:
  * Uses Web2Py's Role-Based Access Control for table-level &/or record-level control (can be separated for C/R/U/D)
   * http://groups.google.com/group/web2py/browse_thread/thread/e4b54f08ec6b66f9

NB 'full' mode requires each permission to be explicitly granted.[[BR]]
We default to having all 'Authenticated' users able to Reade & only 'Administrators' being able to Create/Update/Delete. Administrators can manually add other users to 'Editors' if-required.[[BR]]
Modules can provide further restrictions in {{{models/zzz.py}}}

Whether a user is authorised or not is defined using {{{has_permission()}}} in {{{models/00_db.py}}} & called by the [wiki:BluePrintREST RESTlike controller]

We use {{{auth_group}}} table for Roles & {{{auth_membership}}} to show which roles a user has.
 * admin role initialised in {{{00_db.py}}}
 * 1st user to register gets Administrator role
=== 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 implementation in Many<>Many.[[BR]]
The solution hooks the [wiki:BluePrintREST RESTlike controller] so anything which bypasses that is not logged (other than the simple 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 as 2 checkboxes in the admin settings UI, 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.

----
BluePrints