Domain Object Authorization
Protecting Action Sequences
In a software system, you can secure elements of that system at different levels, depending on your needs. In a web application, you can secure specific URLs. Deeper in the application you might want to secure specific service method calls. And finally, you might want to secure particular instances of objects. This page talks about the last type of security. Users of the Pentaho platform might wish to have a very precise level of control over objects in their solution repository. The Pentaho BI Platform provides this control.
Note: This page describes key security classes in the Pentaho BI Platform. Unless otherwise noted, these classes can be found in
org.pentaho.platform.engine.security
. Class packages will be omitted in the discussion below.Security in the platform is based in part on Spring Security. Classes that are part of Spring Security are marked with SS.
SecurityHelper
SecurityHelper
is an important class because it shields client code from the complexity of the security implementation (e.g. voters, ACL holders, etc). Below is a class diagram along with the two clients that use SecurityHelper
for authorization purposes.
Access Control Lists
In the Pentaho BI Platform, objects in the solution repository (e.g. files and directories) can be secured using access control lists (ACLs). You can have any number of entries in an ACL--each specifying a different recipient.
acl-files
Only a subset of the files in the solution repository can have ACLs. This is specified in the acl-files
element in pentaho.xml
. It is a comma-separated list of file extensions, without dots.
<acl-files>xaction,url,prpt,xdash,xcdf</acl-files>
ACL Entries
An entry in an access control list consists of a recipient, permissions, a reference to the object to which the ACL entry applies, and optionally the parent of the object to which the ACL entry applies. The default ACL entry type in Pentaho is PentahoAclEntry
. This class extends AbstractBasicAclEntry
SS.
Recipients
PentahoAclEntry
stores a recipient as an Object
. In practice, recipients can be of two types: a String
containing a username or a GrantedAuthority
SS containing a granted authority.
Permissions
PentahoAclEntry
stores permissions using bit masks.
Objects and Parents
PentahoAclEntry
stores an object (and its parent) as a AclObjectIdentity
SS.
ACL Holders
An IAclHolder
does exactly what its name implies--it holds or contains an access control list. An ACL is implemented in the platform using a java.util.List
. Inside this list are implementations of AclEntry
SS
Solution Repository Objects
Once you have a container for an ACL, how is it associated with objects in the solution repository? That is where the interface IAclSolutionFile
comes in. This interface extends IAclHolder
and is implemented by org.pentaho.platform.repository.solution.dbbased.RepositoryFile
. RepositoryFile
also implements AclObjectIdentity
SS. So not only does a RepositoryFile
store an ACL (since it implements IAclHolder
), it also is a securable object (since it implements AclObjectIdentity
) SS.
Persistence
The Pentaho BI Platform uses Hibernate for reading and writing to the db-based repository. The PRO_FILES
table contains solution repository objects while the PRO_ACLS_LIST
table contains ACL entries associated with those objects. Below are (incomplete) listings of the columns of each of these tables.
PRO_FILES
Table
FILE_ID |
REVISION |
PARENT |
FILENAME |
FULLPATH |
DATA |
DIRECTORY |
LASTMODIFIED |
CHILD_ID |
FILE_ID
is the primary key. REVISION
is used internally by Hibernate. PARENT
is a reference (by file id) to the object's parent. DIRECTORY
is a boolean that is true if this object is a directory and false if this object is a file. CHILD_ID
is used to find the children files of a directory.
PRO_ACLS_LIST
Table
ACL_ID |
ACL_MASK |
RECIP_TYPE |
RECIPIENT |
ACL_POSITION |
Technically, rows in this table represent ACL entries, not ACLs. An ACL for an object can be created by querying for all rows sharing the same ACL_ID
. ACL_ID
is a foreign key that references PRO_FILES.FILE_ID
. ACL_MASK
is the decimal representation of the bit mask that represents the permission bits enabled in this ACL entry. Example: Given an ACL_MASK
of 3, use the permission bits table below to find the bits that add up to 3. In this case, 3 means that bits Execute and Subscribe are enabled. (The bit for Full control is a special case. Its decimal value denotes the enabling of all permission bits current and future. Do not use it in your sum calculations.) RECIP_TYPE
is 0 for a user and 1 for a role. And RECIPIENT
is the username or granted authority that is the recipient of this ACL entry. Finally, ACL_POSITION
is the order that the access control entry (ACE) appears in the access control list (ACL).
Permission bits
Permission |
Decimal value |
---|---|
Execute |
1 |
Subscribe |
2 |
Create |
4 |
Update |
8 |
Delete |
16 |
Update permissions |
32 |
Full control |
-1 |
Voters
For every domain object, there is exactly one access control list. Add to that a user that wants to perform some operation on that object and that adds up to three inputs: a recipient, an operation, and an ACL. But what makes the "access granted" or "access denied" decision given these three pieces of information? The answer to that question is an IAclVoter
. An instance of IAclVoter
contains an all-important hasAccess
method. It takes the three aforementioned inputs and returns a boolean result: true
meaning access granted and false
meaning access denied. An ACL voter is a singleton; there is only one instance per Java virtual machine.
One might ask: How many ways can a voter arrive at a decision? Assume that user sally
has the following granted authorities: ROLE_DEV
and ROLE_MGR
. Also assume that the ACL for a particular object contains the following entries: (sally
, read
), (ROLE_DEV
, readwrite
). Both ACL entries are applicable to sally
since the first specifies sally
(and she is sally
) and the second specifies ROLE_DEV
(and she has been granted the ROLE_DEV
authority). Should the voter grant or deny a request to write to the object associated with this ACL? This is where extensibility of the voting system comes in. The Pentaho BI Platform provides multiple implementations of IAclVoter
that each make different decisions in this situation! As the administrator of the platform, you decide how access decisions are made through your choice of IAclVoter
. Here are the IAclVoter
implementations provided out-of-the-box.
ACL Management
There are multiple ways to make changes to ACLs. The first is called ACL Publishing and is a "batch-mode" method. Batch-mode means that ACLs are applied to all files and folders in the solution repository according to some rules in a single operation. This is the method that the platform itself uses to apply the initial set of ACLs when the platform first starts up. The final two ways to make changes to ACLs allow you to change the ACL of a single folder or file using a graphical user interface.
To summarize the ACL management methods:
Method Name |
Method Type |
Description |
---|---|---|
ACL Publishing |
batch |
Assigns ACLs to files and folders in the solution repository according to rules in |
Permissions Editor |
single |
A legacy interface for managing ACLs on individual files and folders. Accessible only by Administrators. |
Share tab of Properties dialog |
single |
An interface for managing ACLs on individaul files and folders. Accessible by any user that has Grant Permissions (aka Share) permission on the given file or folder. |
The following permissions are available to be used in access control entries:
Permission |
Meaning |
---|---|
Schedule |
Recipient is allowed to schedule a file. |
Execute |
Recipient is allowed to execute a file. This is analogous to a traditional Read permission. |
Update |
Recipient is allowed to overwrite a file with his/her changes. |
Create |
Recipient is allowed to create files in a directory. |
Delete |
Recipient is allowed to delete files or directories in a directory. |
Grant Permissions |
Recipient is allowed to share a file with others. More generally, user is allowed to modify the ACL of a file. |
All |
Recipient is allowed to do anything including any new permissions added in the future. |
ACL Publishing (Batch Mode)
The db-based solution repository (the default) is refreshed from the filesystem. In other words, solution repository objects are created as files on the filesystem and those objects are refreshed (published) to the db-based solution repository. In the filesystem, solution repository objects have no associated ACLs--at least as far as the platform is concerned. But once solution repository objects are published to the db-based repository, they do have associated ACLs. So how did the objects get their ACLs? The answer is an IAclPublisher
. There is only one IAclPublisher
instance per JVM and the type of that instance is specified in pentahoObjects.spring.xml
.
Note that an IAclPublisher
is only responsible for the initial publishing of ACLs. After the file system is initially published, the Share tab in PUC should be used to tweak permissions.
Configuring Default ACLs
The default Pentaho ACL Publisher (defined in pentahoObjects.spring.xml
) requires a section in pentaho.xml
to tell it what the default ACLs are. Here is a sample properties definition for the provided default ACL Publisher (org.pentaho.platform.engine.security.acls.AclPublisher
).
<pentaho-system> <acl-publisher> <!-- These acls are used when publishing from the file system. Every folder --> <!-- gets these ACLS. Authenticated is a "default" role that everyone --> <!-- gets when they're authenticated (be sure to setup your bean xml properly --> <!-- for this to work). --> <default-acls> <acl-entry role="Admin" acl="ADMIN_ALL" /> <acl-entry role="cto" acl="ADMIN_ALL" /> <acl-entry role="dev" acl="EXECUTE_SUBSCRIBE" /> <acl-entry role="Authenticated" acl="EXECUTE" /> </default-acls> <!-- These acls are overrides to specific file/folders. The above default-acls will be applied and then these overrides. This allows for specific access controls to be loaded when the repository if first populated. Futher changes to acls can be made in the platform GUI tool. Uncomment these and change add or delete to your hearts desire --> <!-- <overrides> <file path="/pentaho-solutions/samples/bursting"> <acl-entry role="Admin" acl="ADMIN_ALL" /> <acl-entry role="cto" acl="SUBSCRIBE_ADMINISTRATION" /> <acl-entry role="dev" acl="EXECUTE_SUBSCRIBE" /> <acl-entry role="Authenticated" acl="NOTHING" /> </file> <file path="/pentaho-solutions/samples/datasources/MDX_Datasource.xaction"> <acl-entry role="Admin" acl="ADMIN_ALL" /> <acl-entry role="cto" acl="ADMIN_ALL" /> <acl-entry role="dev" acl="EXECUTE_SUBSCRIBE" /> <acl-entry role="Authenticated" acl="EXECUTE" /> </file> </overrides> --> </acl-publisher> </pentaho-system>
Node Name |
Purpose |
Required * |
Values |
Default |
---|---|---|---|---|
|
Parent for related elements. |
No |
|
|
|
Parent for related elements. This node contains default ACLs that can be overridden in the |
No |
|
|
|
The role to which these ACLs apply. Exactly one of |
Yes 1 |
string |
|
|
The username to which these ACLs apply. Exactly one of |
Yes 1 |
string |
|
|
The string representation of the ACL integers defined in |
No |
{{NOTHING |
|
|
Parent for related elements. This node contains ACLs that override those ACLs specified in |
No |
|
|
|
Parent for related elements. |
No |
|
|
|
The solution-relative path to the action sequence whose ACLs will be overriden. |
Yes |
filesystem path |
|
|
The role to which these ACLs apply. Exactly one of |
Yes 1 |
string |
|
|
The username to which these ACLs apply. Exactly one of |
Yes 1 |
string |
|
|
The string representation of the ACL integers defined in |
No |
{{NOTHING |
|
1 Either role
or user
is required. Specifying neither of them is invalid, as is specifying both of them.
2 The @
notation is XPath-like notation and it simply denotes an XML attribute.
Permissions Editor via the Legacy Admin Menu
Administrators can manage ACLs using a graphical interface available through the Admin menu. Once inside Admin, click Permissions to start the manager. To access the Permissions Editor, you must be logged in as an administrator to the platform. Also, ACLs are available only if you are using the RDBMS solution repository. This feature is not available for the file-based solution repository implementation.
This graphical user interface is accessible via the legacy Admin menu http://host:port/pentaho/Admin
.
In the sample page above, the tree on the left represents all of the solution repository objects in your solution repository. You can set permissions on any level in the solution repository object tree. Setting permissions on lower level objects in the tree overrides permission settings higher in the tree. Conversely, if you set a permission on a solution repository object that has children, and the children do not have specific permissions set, they inherit the permissions settings from their parent. So, for example, if you set Execute permissions for JoeUser on the analysis directory, then the query1.xaction object inherits that Execute permission; however, if you then set Create and Execute permission on the query1.xaction for JoeUser, these permissions are honored for that object, but other children of the analysis object would still only have their parent's (analysis directory) Execute permission.
Each solution repository object can have any number of permission-role or permission-user combinations set. The middle panel in the sample page above lists the access control list entries defined for the solution repository object selected in the tree. You can modify the permissions for the roles or users that are defined in the existing access control list entries:
- Next to the role or user you want a change to be applied, enable or disable the check box for the permission you want to grant or remove.
- Click Update... to submit the change.
- Click Reset to reverse changes that have not yet been submitted.
Follow the steps below to add a new access control list entry:
- Click Add under the access control list entry table. You see a new list appear on the right that lists all roles and users available to the system.
- Select the roles and/or users that you want to grant permissions to, and then select the permissions that you would like them to receive.
- Click Add at the bottom of the New Permission panel to add your newly defined access control list entries.
Note: If your organization has many users and/or you want to create ACL entries using roles only, you can increase performance by adjusting the settings contained in the
access-ui
node inpentaho.xml file
.
Share Tab on the Properties Dialog within Pentaho User Console
In the Pentaho User Console, use the Browse pane to locate a folder. If you want to manage the ACL of a folder, right-click the folder and click Properties. If you want to manage the ACL of a file, right-click the file in the Files pane and click Properties.
Use the Share tab on the Properties dialog to specify which users or roles have what kind of permission on the given file or folder. Note that folder permissions are inherited if a given folder does not specify an ACL of its own.