eoq3pyaccesscontroller 2.9.1
Access control for an eoq3 DomainWithMdb
Requires Python: >=3.10

# eoq3pyaccesscontroller - Access control for an eoq3 DomainWithMdb

 An access controller that will check users and permissions based on a user db stored in the domain.

# Permissions
Access controll is based on permissions similar to Linux file permissions, but related to CRUD commands.
Every model element can be attached permissions in the form 

    <feature name or *:str>:<permission:int>
	
e.g. owner has full access, group can read and anybody has no access:

    name:0xF40
	
*Feature name* is any feature belonging to the M1 model element or any feature defined by M2 level. 
\* is the wildcard making permissions applicable to any feature.

*Permission* encodes access to CRUD operations for owner, group and anybody as integer value 

          owner  |  group  | anybody
         C R U D | C R U D | C R U D     
    Bit: 1 1 1 1 | 1 1 0 0 | 0 1 0 0

Wheras 1 is access and 1 is no access. 

Permissions can be stored in the \*PERMISSIONS feature of every element.

\*PERMISSIONS can be protected by permission, e.g. only the owner might issue permissions.

## Users and groups 

Access is based on users and groups. A user is an individual with model access rights. 
A group comprises multiple users.

Each model element can be assigned a

* \*OWNER the username of valid user
* \*GROUP the group name of an existing group

Users and group are stored in the MDB as an domain-specific model. 

In order to change users and groups during runtime the model elements must be changed. 

The elements of the users model can be protected by permissions just like any other 

## Permission propagation

If an element has no permissions assigned permissions are propagated from other elements as

1. Is there a permission of the M2 concept this element instantiates?
2. Does the parent element have permissions defined. This chain is followed until no parent is existing any more.
3. Are there general permissions defined.

It is wise to define at least some general permission, e.g. preventing any access by anybody.

The propergation chain stops if any of the steps results in a applicable permission other than no permission defined.
	
## Usage

If access controller is used, a user must sign on with name and password using a unique session ID.
The session ID can be generated by the user. 

### API

Also see Test/Eoq3/test_pyaccesscontroller.py

Imports:

    from eoq3pyaccesscontroller import *
    from eoq3pyaccesscontroller.model import *
    from eoq3.accesscontroller import PERMISSION_STR_SEPERATOR
	
Define initial users and credentials. Help on passhashes is given below.

    users = [
        UserRecord('aco'  ,'6YWjbes/C6HhQqLxCgJFwNSrI5knt/aWBohd7x8YACLPuZ6lm4OZrzglStMjWq1yMb2ivB+7PjmnttuetAmI3Q==',['users','aco','usermanager'],[],[]), # #access controller, pw = aha1289?
        UserRecord('mpl'  ,'8pbSKGXIJnIaRBBWpPUtgZpqHt5Hb+9CTY6/ZRlofv684iCKKmRUt5vxL+RyKvvI4z1KKbx3LYdYlaH2WnWoJA==',['users','mpl','usermanager'],[],[EVT_TYPES.CRT, EVT_TYPES.UPD, EVT_TYPES.DEL]), #model persistency, pw = mpl6333! 
        UserRecord('aha'  ,'L1GBFu8MH6n9wR1VGLswUUqhj+362IBpbJDeD3irbPYMAY6QET3h7qJrYW/tfdh0Uz5qIgAElmh1+hCUdsGzAA==',['users','aha'],[EVT_TYPES.UPD],[]), #action handler, pw = aha9873!
        UserRecord('user1','Xw7SbvM5sX5eH+A/aqsKmgWs9PFrk1awbmXN46pOdyRxQV98Hf/E+AHAbWgM9nsD5u58XngMT34lCAoRPfWGPw==',['users'],[EVT_TYPES.UPD, EVT_TYPES.MSG],[]), #normal user, pw = user2390=
        UserRecord('user2','L1GBFu8MH6n9wR1VGLswUUqhj+362IBpbJDeD3irbPYMAY6QET3h7qJrYW/tfdh0Uz5qIgAElmh1+hCUdsGzAA==',['newbies'],[],[]), #user with no rights, pw = aha9873!
        ]
		
Define generic permissions:

    permissions = [
        GenericPermission('*',MXELEMENT.OWNER,None,None,0xF44), #only the owner can change the ownership
        GenericPermission('*',MXELEMENT.GROUP,None,None,0xFF4), #only the group can change the group
        GenericPermission('*',MXELEMENT.PERMISSIONS,None,'usermanager',0xFF4), #make usermanager the default group for permission modifications
        GenericPermission(ACCESS_SETTINGS_CLASSES.ACCESSSETTINGS,'*','aco','usermanager',0xFF0),
        GenericPermission(ACCESS_SETTINGS_CLASSES.USER,'*','aco','usermanager',0xFF0),
        GenericPermission(ACCESS_SETTINGS_CLASSES.GENERICPERMISSION,'*','aco','usermanager',0xFF0),
        GenericPermission('*','*','superadmin','users',0xFF0) #default permissions
        ]
	

Initialize a local domain with accesscontroller:

    mdb = PyEcoreMdb()
    ac = PyAccessController(users, permissions, superAdminPasshash='TlpM6TEGROrGX17M/t7twkUVHNxEnA7Ykb+ruD5Pjn9HdtSZ9No2/b4gLfKkguzEjS0hTI4DL+1jXJ9oTmeUAQ==' ,config=config) #set the admin password to this "thisIsTheUnitTest!"
    domain = DomainWithMdb(mdb, ac)
    #access controller
    domain.Do(Hel('aco','aha1289?'),acoSession) 
    ac.Connect(domain,acoSession)
	
### Passhash generation

API:

    from eoq3pyaccesscontroller.util.passhash import GeneratePasshash
	
	GeneratePasshash("password123")


CLI:

	pyaccesscontroller.util.generatepashhash.py -pw <your password>

## Documentation

For more information see EOQ3 documentation: https://eoq.gitlab.io/doc/eoq3/

## Author

2024 Bjoern Annighoefer