Data objects support data security rules that apply to categories and columns in data models. Data security rules appear in the Data Security node in the Outline view of a data object. For most effective use of data security rules, create multiple data sets and link them in the data model rather than using a single data set. For information about creating data models, see Creating data objects.
To access data, a user must meet the requirements of every security rule applied to the data. Typical security rules use a combination of security IDs and data values. User access information is provided by the BIRT iHub and volume that provide the data object. For example, the following two security ID requirements apply to customer data:
Rule 1: Senior Executive OR Manager
Rule 2: Senior Executive OR datasetrow["COUNTRY"]
To see all the customers for a particular country, the user must be either a member of the Senior Executive user group or a member of both the Manager user group and the user group for that country.
To manage data security rules, use BIRT Designer Professional to create or open a data model in a data object. Then, choose Define Security. The Data Security Rule manager supports creation, editing, and deletion of data security rules, as described in the following sections. Use the Data Security Rule manager to manage multiple rules. Opening the Data Security Rule manager displays a list of the rules available in the data model, as shown in Figure 11‑1.
Figure 11‑1 List of data security rules in the Data Security Rule manager
The Outline view displays the security rules defined in the data model, as shown in Figure 11‑2. Use this view to edit, assign, or delete a single security rule.
Figure 11‑2 Outline view of data security rules
Structure of a data security rule
A data security rule uses an expression to return a Boolean value: true or false. This expression can use JavaScript or EasyScript. Both script types support using data fields in categories or data sets in the data model in the expression. The following examples of JavaScript and EasyScript expressions that prevent access to records from particular countries are equivalent.
hasUserACL( ) returns the following values based on its optional argument:
If the argument is omitted, hasUserACL( ) returns true.
If the argument is a string, hasUserACL( ) returns true if the user has the security ID specified by the string.
If the argument is an array of strings, hasUserACL( ) returns true if the user has any security ID specified in the array.
The following JavaScript expression provides access to the data row for a user who is either a member of the Senior Executive user group or a member of the user group for the country:
For example, if the value of the COUNTRY field in the data row is "France", the user must be either a member of the Senior Executive user group or a member of the France user group.
EasyScript does not provide access to hasUserACL( ), so security IDs cannot be checked in an EasyScript expression. EasyScript only supports simple usage of data fields and EasyScript functions to return the true or false value for a data security rule.
Effects of data model changes
Adding or removing categories, data sets, and fields from a data model has the potential to affect the behavior of a data security rule. These actions affect the fields available to the rule and the links between data sets.
Whenever a data object is opened or saved using BIRT Designer Professional, the data model structure and its security rules are checked for internal consistency. Consistency errors include missing fields or categories used by a data security rule or missing joins between the data sets in the data model.
If BIRT Designer Professional detects an inconsistency between a rule definition and the available data structures, the Problems view links to any rules that have a problem, as shown in Figure 11‑3.
Figure 11‑3 Problem for a data security rule referring to a nonexistent column
Double-clicking the problem in the list opens the XML source for the data security rule. After identifying the rule having the problem, open the data security rule editor, as described in Data security rule creation and assignment, and correct the problem.
Data security rule creation and assignment
The Data Security Rule manager provides an editor and expression builder to create or edit data security rules. Use the expression builder in the same way as for creating any other expression. Only the JavaScript expression builder supports the hasUserACL( ) function that checks security IDs.
Data security rules are assigned to one or more categories and columns in a data model in a data object. For example, if only users that have a security ID for a country may access customer and order information for that country, assign a data security rule based on a country column to both the customer and order categories. If only managers can see the particular details for a customer that has a bad credit rating, assign a data security rule based on the Manager user group to the sensitive column.
How to create a data security rule and assign it to a category
To create a data security rule and assign it to a category, first create or open a data object that contains a data model. Then, perform the following steps. This example shows the effect of securing the customers category by requiring both country and manager security IDs.
1 Double-click the data model. The data model designer appears.
2 Create a data security rule:
1 Choose Define Security. Data Security Rules appears.
2 Choose New. Data Security Rule appears.
3 Type a meaningful name and description. Then, choose the JavaScript expression builder.
4 In the expression builder, type the following expression that tests for a fixed security ID:
hasUserACL( "Manager" )
5 Validate the expression. Then, choose OK.
6 In Data Security Rule, in Assign to, select one or more categories. The data security rule looks like the one in Figure 11‑4.
Figure 11‑4 The ManagerRule data security rule
Choose OK. In Data Security Rules, choose OK. If data security was not enabled on the data object, the message shown in Figure 11‑5 appears.
Figure 11‑5 Enable data security message
3 Save the data object.
4 Open or create a report design that uses the category protected by the new data security rule. Test the rule as described in How to use BIRT Designer Professional to test a data security rule. The report shows no records if you type an Access Control List that does not include Manager.
5 In the data model, create a second data security rule:
1 Choose Define Security. In Data Security Rules, choose New. In Data Security Rule, type a meaningful name and description. Then, choose the JavaScript expression builder.
2 In the expression builder, enter an expression that tests for a data value as a security ID. First, type:
hasUserACL( )
3 Position the cursor between the parentheses. Select a data field from a category or data set and double-click it to insert in the expression, which looks similar to the following one:
hasUserACL( dataSetRow["Country"] )
4 Validate the expression. Then, choose OK.
5 In Data Security Rule, in Assign to, select one or more categories. The data security rule looks like the one in Figure 11‑6.
Figure 11‑6 The CountryRule data security rule
Choose OK. In Data Security Rules, choose OK.
6 Save the data object.
7 Open the report design that uses the category protected by the new data security rule. If you did not close the report design after the previous test, BIRT Designer Professional displays a message that the data object has changed. Choose OK. Test the rule as described in How to use BIRT Designer Professional to test a data security rule. The report shows no records if you type an Access Control List that does not include both Manager and a valid data value, such as the one shown in Figure 11‑7.
Figure 11‑7 Impersonating a user having the security IDs, Manager and Philippines
The report for this Access Control List looks like the one in Figure 11‑8.
Figure 11‑8 The customer report for a user having the security IDs, Manager and Philippines
How to use BIRT Designer Professional to test a data security rule
To test a data security rule, first create or open a report design that uses live data protected by the data security rule, as described in How to create a data security rule and assign it to a category. Then, perform the following steps. The example shows the effect of securing customers by country.
1 Choose Run➛View Report with Data Security➛In Web Viewer. Run Report with Data Security Enabled appears.
2 To test a user having no security IDs, clear any text in the input field and choose OK, as shown in Figure 11‑1.
Figure 11‑1 Impersonating a user having no security IDs
The report appears in the web browser and displays no secured data. For example, the report in Figure 11‑2 shows no customers.
Figure 11‑2 A report showing no customer information
3 To test a user having one or more security IDs, choose Run➛View Report with Data Security➛In Web Viewer. In Run Report with Data Security Enabled, type the security IDs in the input field and choose OK, as shown in Figure 11‑3.
Figure 11‑3 Impersonating a user having the security ID, France
The report appears in the web browser and displays data secured by that security ID. For example, the report in Figure 11‑4 shows customers in France.
Figure 11‑4 A report showing information about customers in France
How to create and assign a data security rule using multiple security IDs
To create and assign a data security rule using multiple security IDs, first follow the steps described in How to create a data security rule and assign it to a category. Then, perform the following steps. The example shows the effect of securing customers by requiring either country or manager security IDs.
1 Double-click the data model. The data model designer appears.
2 Create a data security rule using multiple security IDs:
1 Choose Define Security. In Data Security Rules, choose New. In Data Security Rule, type a meaningful name and description. Then, choose the JavaScript expression builder.
2 In the expression builder, enter an expression that tests for a data value as a security ID. First, type:
hasUserACL( ["Manager", ] )
3 Position the cursor before the closing square bracket (]) character. Select a data field from a category or data set and double-click it to insert in the expression, which looks similar to the following one:
hasUserACL( ["Manager", dataSetRow["Country"]] )
4 Validate the expression. Then, choose OK.
5 In Data Security Rule, in Assign to, select one or more categories. The data security rule looks like the one in Figure 11‑5.
Figure 11‑5 The ManagerAndCountryRule data security rule
Choose OK.
3 Remove assignments for any other rules on the categories used by the new rule. For each rule assigned to the categories used by the new rule:
1 In Data Security Rules, select the rule. Choose Edit.
2 Deselect the categories used by the new rule.
Choose OK.
4 In Data Security Rules, choose OK.
5 Save the data object.
6 Open the report design that uses the category protected by the new data security rule. If you did not close the report design after the previous test, BIRT Designer Professional displays a message that the data object has changed. Choose OK. Test the rule as described in How to use BIRT Designer Professional to test a data security rule. The report shows no records from a category if you type an Access Control List that does not include either Manager or a valid data value. If you type Manager, all records appear. If you type a valid data value, a subset of records appears, as shown in Figure 11‑6.
Figure 11‑6 The customer report for a user having the security ID, Japan
How to assign a data security rule to a column
To assign a data security rule to a column, first create or open a data object that contains a data model. Then, perform the following steps. This example uses the rule defined in How to create and assign a data security rule using multiple security IDs to show the effect of requiring either country or manager security IDs to view order detail values.
1 Assign a security rule to a column.
1 Use a security rule similar to the following one:
hasUserACL( ["Manager", dataSetRow["Country"]] )
2 In Assign to, expand a category and select one or more columns, as shown in Figure 11‑7.
Figure 11‑7 Assigning the ManagerAndCountryRule rule to columns
For a column secured by the rule, the report shows no rows if you type an Access Control List that does not include either Manager or a valid data value. If you type Manager, all records appear. If you type a valid data value, a subset of records appears, as shown in Figure 11‑8.
Figure 11‑8 The order values report for a user having the security ID, Finland
Rule 1: Senior Executive OR Manager
