System

title: "Access Control List (ACL)" ---

Access Control List (ACL)

The ACL submodule of the System module manages role-based authorization for secured artifacts in the application — primarily UI pages. It records which roles may read, write, create, delete or administer which artifacts, and exposes that information to the framework’s security layer through the AclAuthorizationService contract. It depends on the User submodule (sys.usr) for roles and users, and on the Localization submodule (sys.loc) for the user’s locale during sign-in.

Concepts

Object Type

A category of secured artifact. The bootstrap installs a single built-in type called Page, representing UI page classes that live on the classpath under a configured base package.

Object Identity

A concrete secured artifact within an object type — for example, a particular UI page. It is identified by its object type plus an object code, and carries a reference to the underlying Java class.

ACL Entry

A row that grants a single Role a set of permissions on a single Object Identity. The five permissions — read, write, create, delete and administer — are independent booleans.

Role

Defined by the User submodule (sys.usr). A user inherits roles directly (through UserRole) and indirectly through user-group membership (UserGroupMember → UserGroupRole).

Entities

@startuml

class SAclObjectType {
    **aclObjectName**
    packageName
}

class SAclObjectIdentity {
    **aclObjectType**
    **aclObjectCode**
    description
    className
    aclObjectKey
    aclObjectStatus
}

class SAclEntry {
    **aclObjectIdentity**
    **role**
    aclRead
    aclWrite
    aclCreate
    aclDelete
    aclAdminister
}

class Role {
    code
    description
}

SAclObjectType "1" --* "n" SAclObjectIdentity
SAclObjectIdentity "1" --* "n" SAclEntry
Role "1" --* "n" SAclEntry

@enduml

ACL Object Type (SAclObjectType)

Registers a category of secured artifact.

FieldDescription

Name (aclObjectName)

Unique name of the type (business key). The bootstrap installs Page.

Package (packageName)

Base Java package that is scanned to discover identities of this type. Optional.

ACL Object Identity (SAclObjectIdentity)

Represents one secured artifact inside an object type.

FieldDescription

Object Type (aclObjectType)

Owning object type. Part of the business key.

Code (aclObjectCode)

Code, unique within the object type. Part of the business key.

Description (description)

Short description, up to 30 characters.

Class Name (className)

Fully-qualified Java class name backing the artifact. Optional.

Object Key (aclObjectKey)

Optional domain key used by the remoting layer.

Status (aclObjectStatus)

Lifecycle status, see below. Defaults to Draft.

The status is one of:

StatusCodeMeaning

Draft

D

Newly created identity, not yet validated.

Valid

v

The class is loadable but no ACL Entry has been created yet.

Active

A

The class is loadable and at least one ACL Entry exists.

Invalid

I

The class could not be loaded; the artifact is no longer present on the classpath.

ACL Entry (SAclEntry)

Grants a Role a set of permissions on a single ACL Object Identity. The combination (aclObjectIdentity, role) is unique.

FieldDescription

Object Identity (aclObjectIdentity)

The artifact to which the entry applies. Part of the business key.

Role (role)

The role that receives the permissions. Part of the business key.

Read (aclRead)

Permission to view the artifact.

Write (aclWrite)

Permission to modify existing records.

Create (aclCreate)

Permission to create new records.

Delete (aclDelete)

Permission to delete records.

Administer (aclAdminister)

Administrative permission, e.g. manage other users' rights.

All five permission flags are independent booleans (GBoolean); a missing flag is treated as false.

Functionality

Bootstrap

SYS_ACL_Bootstrap is invoked the first time the default user signs in, through DefaultAclAuthorizationReaderService.getAclUserDetails. It chains the bootstraps of the Localization (sys.loc) and User (sys.usr) submodules and then runs the ACL bootstrap (AclBootstrapService.bootstrap):

  1. If no ACL Object Type named Page exists, it is created with the base package com.wercstat.erp.client.

  2. AclObjectTypeImportService.importAclObjectIdentities is then called to scan that package and seed identities and admin entries.

The constants used during bootstrap are defined in SYS_ACL_Constant:

ConstantDefault value

DEFAULT_ACL_OBJECT_TYPE

Page

DEFAULT_ROLE

sys_ope

ACL_OBJECT_TYPE_BASE_PACKAGE

com.wercstat.erp.client

Importing object identities

AclObjectTypeImportService.importAclObjectIdentities(hasTrace, aclObjectType) discovers UI page classes by reflection (AclReflectionService.findUIPageClassNamesInPackage) within the package configured on the object type. For every discovered class:

  • If no ACL Object Identity with that class name exists, a new identity is created. Its Code is the class' simple name (with a fallback to the fully-qualified name when there is no package suffix), its Description is the simple name truncated to 30 characters, and its Class Name is the fully-qualified name.

  • The default administrator role (sys_ope) is then granted full permissions — read, write, create, delete and administer — through a new ACL Entry, unless one already exists for that identity and role.

The method returns the number of newly-created identities. It is also invoked from the UI through the aclImportObjects action on the ACL Object Type view model.

Validating object identities

AclWriterService.validateAclObjectIdentities walks every ACL Object Identity and tries to load its Class Name:

  • Class loads, identity has no entries → status set to Valid.

  • Class loads, identity has entries → status set to Active.

  • Class fails to load → status set to Invalid.

The method returns the count of identities marked Invalid. It is invoked from the UI through the aclValidateObjects action on the ACL Object Type view model, which then renders either a success message or an error message containing the invalid count.

Resolving a user’s roles

AclReaderService.getUserRoles(user) returns the union of:

  • Roles assigned through any UserGroupMember the user belongs to (via UserGroupRole).

  • Roles assigned directly to the user (via UserRole).

Roles are returned as their codes (strings).

Authorization queries

DefaultAclAuthorizationReaderService answers the security layer’s authorization questions. See the Public API section for the contract it implements; the underlying logic combines ACL Entry rows for the user’s roles with a logical OR per permission flag — a permission is granted if any of the user’s roles grants it.

Public API

SYS_ACL_CommandApi and SYS_ACL_QueryApi

Both classes are Spring @Service beans kept as cross-module extension points but currently expose no operations. Other modules that need ACL behavior reach in through the AclAuthorizationService contract or the view model actions described below.

AclAuthorizationService (framework contract)

DefaultAclAuthorizationReaderService implements io.venlo.frame.server.api.AclAuthorizationService and is the public entry point for the framework’s security layer.

getAclUserDetails(usercode)

Returns an AclUserDetails containing the user’s locale, name, password (encoded for the default user the first time it signs in), archived and locked flags, the union of the user’s roles, default page, default data area and desktop preferences (theme and menu bar). Triggers the database bootstrap on the first sign-in of the default user.

getAclObjectTypeEntries(objectType, roleCode)

Returns every ACL Entry of the given role whose identity belongs to objectType, packaged as AclObjectTypeEntries along with the role description and the package name of the object type. Used by management screens that show what a role can do.

getAclAuthorizationByClass(objectType, javaClassName, roles)

Returns the effective AclAuthorization for a Java class, given the user’s roles. The result combines the entries for all matching roles with a logical OR per permission flag.

View model actions

SAclObjectTypeViewModel exposes two actions on the ACL Object Type page; both surface as toolbar buttons.

aclImportObjects

Runs AclObjectTypeImportService.importAclObjectIdentities for the selected object type and reports the number of newly-imported identities through a desktop notification.

aclValidateObjects

Runs AclWriterService.validateAclObjectIdentities and reports either "no errors" or the number of Invalid identities through a desktop notification.