| Version 23 (modified by , 14 years ago) ( diff ) |
|---|
Table of Contents
DeveloperGuidelinesS3Framework | S3AAA
S3 Authentication, Authorization and Accounting
Authentication is the act of establishing or confirming someone's identity.
Authorization is the concept of allowing access to resources only to those permitted to use them.
Accounting refers to the tracking of user actions - an audit trail.
Overview
AAA functions for S3 are implemented in the modules/s3/s3aaa.py module. This module extends the web2py Auth class as AuthS3 (Authentication), and defines additional classes for role management, access control and audit.
Component Location Function AuthS3 modules/s3/s3aaa.py Authentication, Login S3Permission modules/s3/s3aaa.py Authorization of Access, ACLs S3Audit modules/s3/s3aaa.py Data access logging, audit trail S3RoleManager modules/s3/s3aaa.py RESTful method to manage roles and ACLs Admin controllers controllers/admin.py User Management, role management
Authentication
Current user
Interactive Login
HTTP Basic Authentication
Roles
Roles are defined in the auth_group table, which is defined by the AuthS3 module (in modules/s3/s3aaa.py).
Each role as an ID, a unique name and an optional description.
Access permissions are granted to roles, while a user gets permissions by assigning roles to him. Role assignment is stored in the auth_membership table, which is defined by the AuthS3 class (in modules/s3/s3aaa.py).
At the start of every request, the IDs of all roles of the currently logged-in user are stored as list in session.s3.roles (in models/00_utils.py. In cases where the user is logged-in during the request (e.g. by HTTP Basic Auth), a refresh of this list is also triggered by the login_bare() method of AuthS3.
Roles can be managed in the S3RoleManager interface (Administration => User Management => Roles).
The following roles are pre-defined in S3 and cannot be changed:
ID Name Description 1 Administrator system administrator 2 Authenticated all authenticated users 3 Creator currently unused 4 Editor data editor
The first registered user gets the Administrator role assigned.
Users with the Administrator role always have all permissions, and may access all pages in Eden. The Administrator may also manage Users, Roles and ACLs.
Users with the Editor role may access all data with all methods, except they can not manage Users, Roles or ACLs.
Every authenticated user gets automatically the Authenticated role assigned. This role assignment cannot be revoked.
ACLs
Access Control Lists (ACLs) are bit arrays with each bit representing a permissions to access data with a particular method:
Bit Value Permission auth.permission.CREATE 0x01 may create new records auth.permission.READ 0x02 may read or list records auth.permission.UPDATE 0x04 may update existing records auth.permission.DELETE 0x08 may delete records
ACLs are combinations of these bits (by logical OR), e.g. an ACL with the value 0x06 defines permissions to read and update records, while no permission to add or to delete any records.
ACLs are stored per role and request destination in the s3_permission table, which is defined by the S3Permission class (in modules/s3/s3aaa.py).
For every destination (controller/function/table) two ACLs can be defined to be applied depending on whether a user ownes the record or not:
- one ACL for users owning a record (Owner ACL =
oacl) - one ACL for any other user not owning the record (User ACL =
uacl).
If a user ownes a record, then the most permissive of the User ACL and the Owner ACL gets applied, otherwise only the User ACL gets applied.
Record Ownership
Tables can implement a record ownership by adding two meta fields:
Field name Type Description created_by integer (reference auth_user) ID of the user who has created this record owned_by integer (reference auth_group) ID of the group (role) who own the record
These meta fields are contained in both s3_authorstamp() as well as s3_meta_fields().
A user is considered owner of a record if he has either created the record (user ID == created_by), or he is a member of the owner group (owned_by in user roles).
In tables which do not define either of these meta-fields, ownership rules are not applied (uacl only).
Controller/Table Restriction
ACLs can be defined for controllers, or for particular functions inside controllers.
ACLs can additionally be defined for individual database tables.
The controller ACLs are activated by setting the respective controller to restricted=True in deployment_settings.modules (000_config.py):
dvi = Storage(
name_nice = T("Disaster Victim Identification"),
description = T("Disaster Victim Identification"),
restricted = True, # Apply controller ACLs
module_type = 10,
resources = Storage(
dvi_recreq = {"importer" : True},
)
),
If restricted is False or not defined, then the controller falls back to simple authorization.
The Controller ACL can be defined for all functions in a controller, or a particular function inside a controller, where the function-specific ACL overrides the general controller ACL. That means, you can define a general ACL for the pr controller, and a different one for the pr/person function.
The Controller ACLs are applied to all resources when accessed through this controller/function. If the Controller ACL does not specify any permission, the request is rejected as "Unauthorized".
Once the user has passed that controller permission check, and requests access to a particular table, the controller checks for table-specific ACLs. If there are specific ACLs for this table, then the most restrictive of controller and cable ACLs apply (i.e. you cannot allow on the table level what you forbid at the controller level, and vice versa). If there are no specific ACLs defined for this table, then the controller ACLs apply.
