9 Oracle Fusion Applications Data Role Templates

The information in this chapter is specific to Oracle Fusion Applications only.

This chapter describes what data role templates are and the procedures to create, run, and maintain them. It contains the following sections:

• Using Data Role Templates

• Before You Begin

• Creating a Template

• Running a Template

• Updating a Template

• Importing and Exporting a Template

9.1 Using Data Role Templates

A template or data role template specifies key characteristics of external roles and data security policies. These characteristics include:

• A set of base external roles

• A set of dimension values

• A set of naming rules

When run, the data role template generates all the external roles and the data security policies that satisfy the values in the template. The external roles generated (by a template run) are stored in the domain identity store; the data security policies generated are stored in the data security store; templates are stored in the metadata storage (MDS).

The basic principle behind the generation of external roles and data policies is that one can take the cross product of the first two sets of characteristics (external roles times dimension values) to obtain a set of external roles named according to the third set (naming rules), and associate them with a set of permissions, for a given data stripe, in data security policies.

The external roles and the data security policies that a template run generates are specified as a set of external roles and a set of dimensions (rows or attributes returned by an SQL query). Each dimension attribute is associated with an alias, which is used (by the naming conventions) to generate names for the roles and data security policies generated.

A dimension attribute can be the attribute return by an SQL query, such as, the following:

where territory=US, business unit=Finance, and legal entity=North America

The number of external roles generated equals the number of specified external roles times the number of rows returned by the query (or number of dimensions). Each external role generated inherits from the corresponding specified external role.

For example, a template specifying the external roles Employee-Role and Manager-Role, the dimensions US and UK, and the naming rule [external role]:[dimension code name] would generate the following four external roles:

Employee-Role:US, Employee-Role:UK, Manager-Role:US, Manager-Role:UK

Each of the four generated role inherits from one of the specified external roles, Employee-Role or Manager-Role.

The list of external roles and data security policies that a template run generates can be previewed, that is, displayed before the actual creation of roles and associated data security policies takes place.

9.2 Before You Begin

In addition to the data sources listed in Section 1.2, "Installing and Configuring Authorization Policy Manager," the use of templates requires that two other data sources, described in Table 9-1, also be configured.

Table 9-1 Data Sources Required by Templates

Data Source Name	JNDI Name	Description
ApmRgxDimDBDS	jdbc/ApmRgxDimDBDS	Used by role templates to execute dimension SQLs.
ApplicationDB	jdbc/ApplicationDBDS	Stores role template records to create security artifacts.

All data sources can be configured with the WebLogic Console by navigating to JDBC > Data Sources. The data source ApmRgxDimDBDS must be created with a credential that includes the database writing privilege.

9.3 Creating a Template

To create a new template, proceed as follows:

1. Select Global > Role Templates, in the left panel, and then click New to display an Untitled page in the right panel containing six tabs: General, External Roles, Dimension, Naming, Policies, and Summary.

2. In the General tab, enter the following data for the template being created:

   • A display name (required)

   • A name (required)

   • A description (optional)

   • A template group (optional) - This attribute allows searching templates by group and running simultaneously the set of templates in a group.

3. In the External Roles tab, specify the external roles for the template in one of the following ways:

   • Click Add, at the top of the Roles area, to display bring up the Add External Role dialog where you can search for external roles matching a given pattern; then select roles from the results of the query and click Add. The role(s) selected are displayed in the Roles table.

   • Perform a regular search for external roles and drag-and-drop the desired roles from the Search Results list into the Roles table.

   Figure 9-1 illustrates the Roles table in the External Roles tab after two external roles have been added to the table. When the mouse hovers the blue icon, at the right of a role row, the following information about the role is displayed: the role code, the role name, and the role description; these three attributes can always be used in the Naming tab to specify the names of generated roles.

   Figure 9-1 Creating a Template, External Roles

   
   

4. In the Dimension tab, specify the SQL that identifies the dimensions of the template.

   The user must have access privilege to the data queried. The data returned by that SQL is displayed in the Preview Data table. Optionally, enter aliases for the column names of the returned data in the Column Display Names table, at the bottom of the page.

   Figure 9-2 illustrates the Dimension tab with an SQL query, the data returned by it, and display name aliases; the attributes SET_ID, SET_CODE, and SET_NAME can be used in the Naming tab to specify the names of generated roles.

   Figure 9-2 Creating a Template, Dimensions

   
   

5. In the Naming tab, specify the rule to follow to generate names of the data roles created by the template. These names are put together by concatenating several strings that you specify in the area Configure Role Name. Typically, one chooses an attribute of the base role and an attribute of the dimension (such as SET_ID, SET_CODE, or SET_NAME in Figure 9-2); the role attributes Role_Code, Role_Name, and Role_Descrip are available by default. The resulting names must be unique.

   Similarly, specify the rule to follow to generated display names for the data roles created by the template. These names are put together by concatenating several strings that you specify in the area Configure Display Name. The resulting names need not be unique, but it is recommended that you specify enough attributes to make them unique too.

   Optionally, enter a description for the roles generated in the area Description.

   Figure 9-3 illustrates a portion of a Naming tab with naming values for the names and the display names for the external roles generated by the template. Note the following points: (a) the pattern of the concatenation is shown at the bottom of each area after the heading Generates; (b) the use of square brackets in the description to refer to data values.

   Figure 9-3 Creating a Template, Role Naming

   
   

6. In the Policies tab, specify the rules to create data set grants, as follows:

   • In the Database Resource area, use the button Add to add a database resource, that is, the object to be secured by the generated data security grants.

   • In the Data Sets tab, specify wether the grant is using a Primary Key or an Instance Set (the instance set is selected from the available instance sets associated with the resource, which are defined at resource creation), and how the data set is mapped to a dimension attribute.

   • In the Actions tab, specify the actions allowed on the database resource.

   Figure 9-4 illustrates the specification of a data set by a primary key and the corresponding mapping to a dimension attribute; Figure 9-5 illustrates the specification of a data set by an instance set and the corresponding mapping to dimension attributes; and Figure 9-6 illustrates the selection of actions allowed on the database resource.

   Figure 9-4 Creating a Template, Specify Data Set with Primary Key

   
   

   Figure 9-5 Creating a Template, Specify Data Set with Instance Set

   
   

   Figure 9-6 Creating a Template, Specifying Actions

   
   

7. Click Save. Oracle Authorization Policy Manager validates the information supplied and, if all data passes validation, the template is saved and the tab Summary becomes available.

9.4 Running a Template

The roles that a template run generates can be previewed before the creation of security artifacts takes place. The procedures in this section assume that the template (mentioned in the procedures) has been created and saved.

A template or a set of templates can also be run programmatically via web-services. For details, see Section 9.4.1, "Running Templates Programmatically."

To preview the external roles that a template run would generate, proceed as follows:

1. Open the template and bring the Summary tab to the foreground (this tab is available since the template has been saved).

2. Click the button Preview Roles, near the top of the page, to display the Preview Roles dialog, where the external roles that would be generated by an actual template run are grouped in the following five disjoint categories:

   • Valid Roles - Set of roles with no issues.

   • Invalid Roles - Set of roles with no base role in the identity store.

   • Inconsistently Created Roles - Set of roles with identical names to existing roles in the identity store. These roles, typically, get to be included in this category because of a change or deletion in records from where the dimensions are computed.

   • Inconsistently Deleted Roles - Set of roles that have been deleted from the identity store.

   • Missing Link Roles - Set of roles that are missing the link to the parent base role.

   Figure 9-7 illustrates a portion of the Preview Roles dialog with the category Valid Roles expanded.

   Figure 9-7 Previewing Roles, Five Categories

   
   

To run a template, proceed as follows:

1. Open the template and bring the Summary tab to the foreground (this tab is available since the template has been saved).

2. Click the button Generate Roles. The roles generated are displayed in the five disjoint categories mentioned in the preceding procedure. Each external role generated by the run inherits from the corresponding parent external role.

3. Reconcile roles in the following four categories, as appropriate:

   • Invalid Roles - A role in this category is a role for which the base role is not found in the identity store. Delete or allow roles in this set; deleting an invalid role:

     • Removes the role, if it is not being used by any policy.

     • Removes the data security generated for the role.

   • Inconsistently Created Roles - A role in this category is a role with a name identical the name of some other role already in the identity store. Typically, these roles show up because of a change or deletion in records from where the dimensions are computed. Delete or reuse roles in this set; reusing an inconsistently created role:

     • Overwrites the existing role with the generated one.

     • Adds a link between the base role and the role.

     • Refreshes the role's display name and description.

     • Adds the data security for the role.

     • Does not affect data securities defined by other templates.

   • Inconsistently Deleted Roles - Delete or recreate roles in this set; recreating an inconsistently deleted role:

     • Creates the role in the identity store using the template's naming definition.

     • Adds the data security for the role.

     • Adds a link between the base role and the role, if it was not already in place.

   • Missing Link Roles - A role in this category is missing the required link to a base role. Relink roles in this set; relinking a missing link:

     • Adds a link between the base role and the role.

     • Updates the grant associated with the role.

Once external roles and data policy grants have been generated, you can verify that they have been properly created by searching and opening a particular role or policy. Figure 9-8 illustrates how the generated external role Benefits Administrator:Finalcial Mgnt inherits, as expected, from the base external role Benefits Administrator (the names displayed in the External Role Hierarchy table are the role display names, not role names):

Figure 9-8 Generated Role Inheriting from a Based Role

9.4.1 Running Templates Programmatically

The following two functions support running a single template or the collection of templates with a given group id via web-services:

public String executeTemplate(String TemplateName)
public String executeTemplateByGroupId(String GroupId)

The string returned by either of them describes the status of the run. If successful, it identifies the template(s) that were run; otherwise, it identifies the error that was encountered.

9.5 Updating a Template

There are rigorous restrictions on how a template can be changed once it has been run.

• The name of a template cannot be updated.

• The SQL that defines the template dimensions cannot be changed. The data that this SQL accesses, however, can change and, therefore, a new template run may return a different set of dimensions than those returned by the last run.

• When a dimension is added (to the set of dimensions of the last run), the template run creates external roles for the added dimension only.

• When a dimension is deleted (from the set of dimensions of the last run), the administrator can either deactivate the external roles involving the deleted dimension or left them unchanged.

• After execution, the template's naming cannot be updated.

On the other hand, external roles can be added or deleted from a template at any time.

• When an external role is added to a template, a template run creates external roles for the added role and each of the dimensions.

• When an external role is deleted from a template, then the administrator can either deactivate the external roles involving the deleted role or left them unchanged.

Use the following procedure to update a template.

1. Locate the template to update by performing a regular search or an advanced search.

   Data Role Templates can be searched by specifying a template name, display name, and group id.

   1. Select Global > Role Templates in the navigation panel and click Open (the folder icon on top of the panel) to display the Search - Role Templates page.

   2. Enter an operator and a string to match for the template name, an operator and a string to match for the template display name, and an operator and a string to match for the template group id.

   3. Click Search to trigger the search and to display the templates that match the entered specification in the Search Results table.

   4. Double-click an item in the Search Results table to open it.

      Alternately, select the template in the Search Results table and click Open.

2. Click Edit to open the template for editing in the Home area.

3. Modify fields as appropriate and as allowed in the page tabs.

4. Click Apply to save changes.

9.6 Importing and Exporting a Template

A data role template can be imported to or exported from the Oracle Authorization Policy Manager environment with the use of the following two utilities: importMetadata and exportMetadata. Both utilities require establishing a connection to the Oracle WebLogic server before they can be used. The following code illustrates how to establish a connection to a WebLogic server:

> connect ('aUser','aPassword','t5://localhost:7133')

In the code, the first argument is the user name, the second is the password for that user, and the third is the connection URL to the server. The connection so established is terminated with the command exit().

Use the following procedure to import one or more data role templates.

1. Connect to the server.

2. Execute the utility importMetadata, as illustrated in the following sample (the arguments are listed in different lines only for clarity of exposition):

   > importMetadata(application='oracle.security.apm', 
                    server='AdminServer', 
                    fromLocation='/myLocation/myRoleTemplates',
                    docs='/oracle/apps/apm/**', 
                    restrictCustTo='site')
   

   The meaning of the arguments is as follows:

   • application specifies the owner of the data role template to be imported.

   • server specifies the name of the WebLogic server to which one is connected.

   • fromLocation specifies the directory where the data role template to be imported is located.

   • docs specifies the template in the directory fromLocation to be imported. To import all templates (including template subdirectories) in the specified directory, use **, as illustrated in the example above.

   • restrictCustTo is an argument that should always be set to site.

To export a data role template, proceed as follows:

1. Connect to the server.

2. Execute the utility exportMetadata, as illustrated in the following sample (the arguments are listed in different lines only for clarity of exposition):

   > exportMetadata(application='oracle.security.apm', 
                    server='AdminServer', 
                    toLocation='/myLocation/myRoleTemplates',
                    docs='/oracle/apps/apm/**', 
                    restrictCustTo='site')
   

   The meaning of the arguments is identical to those used for importing, except for toLocation, which specifies the location where the data role template(s) should be downloaded.