Image Removed

Image Removed

Image Removed

Image Removed

<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> [{{AbstractBasicAclEntry}}|http://www.acegisecurity.org/multiproject/acegi-security/apidocs/org/acegisecurity/acl/basic/AbstractBasicAclEntry.html] ^Acegi^.

h4. Recipients

{{PentahoAclEntry}} stores a recipient as an {{Object}}. In practice, recipients can be of two types: a {{String}} containing a username or a [{{GrantedAuthority}}|http://www.acegisecurity.org/multiproject/acegi-security/apidocs/org/acegisecurity/GrantedAuthority.html] containing a granted authority.

h4. Permissions

{{PentahoAclEntry}} stores permissions using [bit masks|http://en.wikipedia.org/wiki/Bit_mask].

h4. Objects and Parents

{{PentahoAclEntry}} stores an object (and its parent) as a [{{AclObjectIdentity}}|http://www.acegisecurity.org/multiproject/acegi-security/apidocs/org/acegisecurity/acl/basic/AclObjectIdentity.html] ^Acegi^.

h2. 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}}|http://www.acegisecurity.org/multiproject/acegi-security/apidocs/org/acegisecurity/acl/AclEntry.html] ^Acegi^
{panel:title=IAclHolder Hierarchy|bgColor=#FFFFFF}
!IAclHolder-hierarchy.png|align=center,width=900,height=900|thumbnail!\\
{panel}

h2. 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 {{com.pentaho.repository.dbbased.solution.RepositoryFile}}. {{RepositoryFile}} also implements {{AclObjectIdentity}}. So not only does a {{RepositoryFile}} store an ACL (since it implements {{IAclHolder}}), it also is a securable object (since it implements {{AclObjectIdentity}}).

h3. Persistence

The Pentaho BI Platform uses [Hibernate|http://www.hibernate.org] 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.

h4. {{PRO_FILES}} Table

| FILE_ID | PARENT | FILENAME | FULLPATH | DATA | DIRECTORY | LASTMODIFIED |
{{FILE_ID}} is the primary key. {{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.

h4. {{PRO_ACLS_LIST}} Table

| ACL_ID | ACL_MASK | RECIPIENT |
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 permissions in this ACL entry. And {{RECIPIENT}} is the username or granted authority that is the recipient of this ACL entry.

h2. 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 user of the platform, you decide how access decisions are made through your choice of {{IAclVoter}}.
{panel:title=IAclVoter Hierarchy|bgColor=#FFFFFF}
!IAclVoter-hierarchy.png|align=center,width=900,height=900!
{panel}

h2. 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 the entire solution repository according to some rules.  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.

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

h3. 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 Admin > Permissions interface should be used to tweak permissions.

{anchor:configure_default_acls} 
h4. 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}}).
{code:xml}
<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).                                                       -->
   </acl-publisher>
</pentaho-system>