Access Grant Definitions

An access grant definition is an XML structure that specifies a user’s access rights to different parts of the data defined by an analysis schema. The access grant definition specifies access rights based on roles. Users with a given role have the access rights granted to that role. An access grant definition can also refer to a profile attribute table to control access by way of properties defined for specific users, which allows you to use variable substitution to create simple, flexible access grants.

An access grant definition depends on elements of the analysis schema associated with a connection. That analysis schema must contain cubes with the same name and structure as appear in the access grant definition’s CubeGrant elements. If you specify access grants down to the member level, the references to member values in the access grant definition must be in the database defined by the connection.

You create an access grant definition as an XML file with an AGXML file extension. To use it, import it into the repository, or upload it while creating an analysis client connection, just as you can upload an analysis schema.

The grant definitions for a role lie within the following nested grant elements: SchemaGrant, CubeGrant, HierarchyGrant, and MemberGrant. SchemaGrant is the outermost element, and MemberGrant is innermost. In general, grants within an element override grants in containing elements.

A SchemaGrant element’s access attribute defines the default access for any object in the schema. This attribute can take one of the following values: all, none.

A CubeGrant element’s access attribute defines the default access to hierarchies within the cube specified by its cube attribute. The access attribute can take one of the following values: all, none.

If the schema contains cubes for which no CubeGrant element appears, then the default access defined at the SchemaGrant level applies to those cubes. If a cube contains hierarchies for which no HierarchyGrant element appears, then the default access defined at the CubeGrant level applies to those hierarchies.

A HierarchyGrant element’s access attribute defines the role’s access to the hierarchy specified by the hierarchy attribute. The access attribute can take one of the following values: all, none, custom. The value all grants this role complete access to this hierarchy. The value none grants this role no access to this hierarchy. The value custom means that MemberGrant sub-elements define this role’s access within the hierarchy.

A HierarchyGrant element has optional topLevel and bottomLevel attributes. These define the segment of the hierarchy that users with the given role can see. They can see everything between and including the endpoints. Nothing in an enclosed MemberGrant element can override the topLevel and bottomLevel attributes.

The topLevel and bottomLevel attributes use a dot notation to specify a level in the hierarchy. In the example in Sample Access Grant Definition, the topLevel attribute for the Store hierarchy has the value [Store].[Store.Country]. The [Store] designates the Store hierarchy. The [Store.Country] designates the Country level of the Store hierarchy.

A MemberGrant element has member and access attributes. The member attribute specifies the top level of the hierarchy defined by the enclosing HierarchyGrant element to which the MemberGrant’s access attribute applies. For example, if the member value is [Store].[USA].[CA], the top level to which the access attribute applies is California in the Store hierarchy. The access attribute can take one of the following values: all, none. The value applies to everything including or below the level specified by the member attribute, except that it cannot grant access to anything outside the segment defined by the HierarchyGrant attributes topLevel and bottomLevel.

You can use substitution variables in the grant expressions that specify the values of the topLevel, bottomLevel, and member attributes. The example in Sample Access Grant Definition includes variable substitution.

Jaspersoft OLAP applies grants in the order that you define them. For example, if you grant access to USA and then deny access to Oregon, an affected user cannot see Oregon or any of its children (for example, Portland). But if you deny access to Oregon and then grant access to USA, the user can see Oregon and all of its children.

Granting access to a member also grants access to the levels above it, except that the grant cannot override the HierarchyGrant’s topLevel attribute. For example, if you deny access to USA and then grant access to California, an affected user can see California and USA, but no other states. If the data includes USA totals, they will be based on data from all states.

You can test access grant definitions by creating users with various roles and logging in as them. For more information on roles, users, and the Log in As feature, refer to the JasperReports Server Administrator Guide. The Jaspersoft OLAP Ultimate Guide also includes a detailed implementation example.

Sample Access Grant Definition

The following sample access grant definition (called Foodmart Grant and found in the repository at /analysis/schemas) is used with the Foodmart Mondrian connection, (found in the repository at /analysis/connections):

This schema defines access permissions for a role called StateManager.

In this example, the SchemaGrant element defines none as the default access for all objects in the schema. Users with the StateManager role cannot access anything, unless a lower level grant overrides the default.

The cube attribute has the value Sales, so the definition is for the Sales cube. The access attribute has the value all. This gives users with this role access to the entire Sales cube. Again, lower level grants can override this one.

HierarchyGrant elements define access to the Store, Customers, and Gender hierarchies. Users with this role cannot see any of the gender hierarchy. The other two HierarchyGrant elements define custom access to the Store and Customers hierarchies.

The member grants in this example use substitution variables like %{State} to represent substitutions from the profile attribute table. These particularize the grant to the specific user associated with the StateManager role. For example, suppose user John has StateManager as one of his roles. Also suppose that the profile attribute table has a row in which the values of the columns attribute and values are State, and CA,OR,WA. If you create a view for John, the line:

<MemberGrant member="[Customers].[USA].[%{State}]"

access="all"/>

in the above example is interpreted to mean:

<MemberGrant member="[Customers].[USA].[CA,OR,WA]"

access="all"/>

Working with the Profile Attribute Table

The Jaspersoft OLAP user interface does not provide access to the profile attribute table. You must create and modify this table using the standard tools for working with your underlying relational database management system (RDBMS). This section assumes that the JasperReports Server repository database is hosted by MySQL.

The name of the profile attribute table in the RDBMS is jiprofileattribute. The following table defines it:

+----------------------+--------------+------+-----+---------+----------------+

| Column z| Type | Null | Key | Default | Extra |

+----------------------+--------------+------+-----+---------+----------------+

| id | bigint(20) | NO | PRI | | auto_increment |

| attrName | varchar(255) | NO | | | |

| attrValue | varchar(255) | NO | | | |

| principalobjectclass | varchar(255) | NO | | | |

| principalobjectid | bigint(20) | NO | | | |

+----------------------+--------------+------+-----+---------+----------------

Use the following SQL query to view the current contents of the profile attribute table:

select * from jiprofileattribute

The columns have the following meanings:

Here is an example of possible values for the State variable:

The value 13 represents a user with a role used in the access grant definition (for example, StateManager).

Suppose you have created a role called StateManager and assigned it to a user called CaliforniaManager, using the Jaspersoft OLAP user interface:

You can find the key for the principalobjectid in the profile attribute table by using a query like the following:

select * from jiuserrole where

roleId=(select id from jirole where rolename="StateManager") and

userId=(select id from jiuser where username="CaliforniaManager");

The result of the query looks like this:

+--------+--------+

| roleId | userId |

+--------+--------+

| 21 | 13 |

+--------+--------+

In this case, 13 is the key for the CaliforniaManager user. Use this key to find and update the CaliforniaManager's attributes in the profile attribute table. To update this table, you must run SQL statements against your JasperReports Server repository database. For more information on working with profile attributes, refer to the JasperReports Server Ultimate Guide. For a detailed example of data-level security, including more information on profile attributes, refer to the Jaspersoft OLAP Ultimate Guide.

Best Practices for Designing Access Control

Best practices for designing access control will emerge as you gain experience with this feature. Here are some suggestions to get you started:

•    Review the detailed implementation example found in the Jaspersoft OLAP Ultimate Guide to understand the entire implementation process.

•    Start with a clear description of the requirements before writing XML.

•    Determine the different roles played by users of your application, and assign specific roles to each user.

•    Create a hierarchy in each cube that corresponds in a one-to-one way with the different levels of access. That is, make a hierarchical level that corresponds to a user role. Defining the access control requirements before building the schema is much easier than adding access control after designing the schema.

•    Build your access control definition iteratively. Start with the smallest definition that you can test. When it works properly, add and test additional increments until you have a complete definition.

•    Use an XML editor to help you format access grants properly.