2 Constructing A Policy Programmatically

2.2.1 Accessing the Policy Store

Any policy management activity must be preceded by retrieving an instance of the PolicyStore object. The following procedure shows how the PolicyStore object is retrieved using interfaces in the oracle.security.jps package. Smith is specified as the user with the administrative rights to manage the policies.

1. Retrieve an instance of PolicyStore.

   JpsContextFactory ctxFact = JpsContextFactory.getContextFactory(); 
   JpsContext ctx = ctxFact.getContext(); 
   PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
   if (ps == null) {  
       // if no policy store instance configured in jps-config.xml  
       System.out.println(“no policy store instance configured”);  
       return;  
   }  
   

   JpsContext declares a collection of service instances common to a particular domain in the file that configures Oracle Platform Security Services (OPSS), jps-config.xml. If there is more than one JpsContext defined in the jps-config.xml, the policy store specified in the default JpsContext will be returned. You can also get a particular JpsContext by name. See the Oracle Fusion Middleware Security Guide for more information on this configuration file. Parameters specific to Oracle Entitlements Server are documented in the Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server.

   Notes:

   • If no policy store instance is configured, getServiceInstance() will return null.

   • If a connection is not established, getServiceInstance() throws javax.persistence.PersistenceException.

   • If the PolicyStore object was already retrieved but the connection went down, any operations within the policy store will lead to a PolicyStoreException. If the backend is down, resume operations once the backup is available. High availability for backend stores is also possible.

2. Specify the administrative user.

   Subject smith = new Subject(); 
   Principal principal = new WLSUserImpl("smith"); 
   smith.getPrincipals().add(principal); 
   BindingPolicyStore ps = BindingPolicyStoreFactory.getInstance();ps.setSubject(smith);
   

   It is assumed the user is already authenticated.

2.2.2 Creating an Application Policy

An ApplicationPolicy object is a container for all objects needed to define secure access to a particular application. An ApplicationPolicy object should be created for each target to be secured. You may create as many as needed. Once created, the ApplicationPolicy is represented by the ApplicationPolicy interface which contains the programmatic managers needed to create resources, policies and other security objects used to define the application's access requirements. These security objects comprise those defined in Chapter 1, "Using the Policy Model."

You can create, delete and retrieve ApplicationPolicy objects with the methods found in the PolicyStore interface. Example 2-1 illustrates how to create an ApplicationPolicy object using the createApplicationPolicy() method.

ApplicationPolicy ap = ps.createApplicationPolicy("Trading", "Trading 
 Application","Trading Application."); 

The values of the createApplicationPolicy() parameters are defined as:

• Name - Trading is a unique identifier for the ApplicationPolicy object.

• Display Name - Trading Application is an optional, human-readable name for the ApplicationPolicy object.

• Description - Trading Application. is optional information describing the ApplicationPolicy object.

2.2.3 Defining Resource Types

A ResourceTypeEntry object specifies the full scope of traits for a particular kind of protected resource. It contains resource attributes and definitions of all possible valid actions that can be performed on the protected resource. From the higher level ResourceTypeEntry object (associated with an ApplicationPolicy object), you instantiate a specific Resource object to represent an actual, secured target. Thus, the ResourceTypeEntry must include the full range of actions that may be granted or denied on any Resource instance of this type. The actions added to a ResourceTypeEntry can be standard actions (GET and POST to a URL) or a custom action on a business object (transfer to or from a bank account).

To create, delete, retrieve or modify a ResourceTypeEntry, obtain an instance of the ResourceTypeManager. Example 2-2 creates a ResourceTypeEntry named TradingResType within the TradingApp ApplicationPolicy object. TradingResType has two permissible actions (BUY and SELL) and an attribute named ManagerType .

ResourceTypeManager resourceTypeManager = Trading.getResourceTypeManager();
List<String> actions = new ArrayList();
   actions.add("get");
List<AttributeEntry<? extends DataType>> attributes = new ArrayList<AttributeEntry<? extends DataType>>();
ResourceTypeEntry resType = rtm.createResourceType
  ("TradingResType", "Trading ResType", "Trading Resource Type", 
    actions, attributes, ",", null);

TradingApp is the name of the ApplicationPolicy object from which the ResourceTypeManager is being retrieved. The values of the createResourceType() parameters are defined as:

• Name - TradingResType is a unique identifier for the ResourceTypeEntry.

• Display Name - Trading ResType is an optional, human-readable name for the ResourceTypeEntry.

• Description - Trading Resource Type is optional information describing the ResourceTypeEntry.

• Actions - actions is the name of an ordered collection (list) of all valid actions on the ResourceTypeEntry - in this case, GET. Use the setAllAction() method to set a default action keyword.

• Attributes - attributes specifies a listing of all valid attributes for the ResourceTypeEntry. If there are duplicate ones, they will be handled as one. To define one or more attributes, create them with the createAttribute() method in the ExtensionManager and reference them here. See Section 2.3.3, "Creating Attribute and Function Definitions" for more information. Attributes can also be null.

• Delimiter - / (forward slash) is the default delimeter for the actions. Use the setResourceNameDelimiter() method to set a different delimiter. The delimiter is passed to the method as a ResourceTypeEntry.ResourceNameDelimiter enum.

• Resource Matcher Class - null signifies there is no resource permission matcher class used for target and action matching. To set an implementation of the Java Permission class, assign the class name as the matcher class. In this case, the list of actions supplied under Actions are validated at runtime by the implementation.

ResourceTypeEntry objects can also be defined as hierarchical by invoking the object's setHierarchicalResource() method. By passing true to the isHierarchical parameter, the ResourceTypeEntry will be set as hierarchical. A hierarchical ResourceTypeEntry can then be used to instantiate a ResourceEntry in which the following applies.

1. A policy applicable to a ResourceEntry created from a hierarchical ResourceTypeEntry is also applicable to any ResourceEntry objects that are its children.

2. Any attribute defined for a ResourceEntry created from a hierarchical ResourceTypeEntry is inherited by any ResourceEntry objects that are its children.

The isHierarchicalResource() method can be used to determine whether a ResourceTypeEntry has been set as hierarchical. Additional information is noted in Section 2.2.4, "Instantiating a Resource."

2.2.4 Instantiating a Resource

A ResourceEntry object represents a specific, secured target in a protected application. It can represent software components managed by a container (URLs, EJBs, JSPs) or business objects in an application (reports, transactions, revenue charts). See the Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server for more information on software components and business objects.

To create a ResourceEntry object, obtain an instance of the ResourceManager using the getResourceManager() method in the applicable ApplicationPolicy or PolicyDomainEntry. Following that, use the createResource() method to create the object.

Example 2-3 creates a checking account ResourceEntry. Trading refers to the ApplicationPolicy object from which the ResourceManager is being retrieved.

ResourceManager resMgr = Trading.getResourceManager();
ResourceEntry checkingRes = resMgr.createResource("Bob_checking1", 
 "Bob Checking Account", "Checking account.", resType, null);

The values of the createResource() parameters are defined as:

• Name - Bob_checking1 is the unique identifier for the ResourceEntry.

• Display Name - Bob Checking Account is an optional, human-readable name for the ResourceEntry.

• Description - Checking account. is optional information describing the ResourceEntry.

• Type - resType is the ResourceTypeEntry object from which the resource will be instantiated.

• Attributes - null specifies that there are no (optional) attributes being configured for this ResourceEntry. To define one or more attributes, create them with the createAttribute() method in the ExtensionManager and reference them here (instead of null).

Once a ResourceEntry is created, it can be paired with actions in a ResourceActionsEntry or included in a PermissionSetEntry. For more information, see Section 2.3.4, "Defining Permission Sets."

2.2.5 Associating Actions with the Resource

A ResourceActionsEntry object associates a Resource instance with a set of actions that can be performed on it. The Resource instance is specified as either a static ResourceEntry or a dynamic ResourceNameExpression.

The following sections have more information.

• Section 2.2.5.1, "Using a ResourceEntry"

• Section 2.2.5.2, "Using a ResourceNameExpression"

ResourceEntry checkingRes = resMgr.createResource("Bob_checking1", 
 "Bob Checking Account", "Checking account.",resType, null); 
List<String> actions = new ArrayList<String>(); 
 actions.add(“read”); 
 actions.add(“write”); 
List<ResourceActionsEntry> resActsList = new 
 ArrayList<ResourceActionsEntry>();
resActsList.add(new BasicResourceActionsEntry(Checking, <actions>));

// create one ResourceActionEntry
ResourceNameExpression resExpression = new ResourceNameExpression
  (resTypeName, resNameExp);
ResourceActionsEntry resActionsEntry = new BasicResourceActionsEntry
  (resExpression, actions);
 
List<ResourceActionsEntry> resActionsList = 
   new ArrayList<ResourceActionsEntry>();
resActionsList.add(resActionsEntry);

2.2.6 Specifying a Policy Rule

A PolicyRuleEntry defines an Effect (and optionally a Condition). An Effect specifies the possible outcomes of the policy rule. Effects in Oracle Entitlements Server are GRANT or DENY. When the policy rule is evaluated (coupled with information regarding a principal and a target ResourceEntry), the rights of the subject in terms of the ResourceEntry are determined. All policies must contain one (and only one) Policy Rule. Example 2-6 illustrates how to create a PolicyRuleEntry object named myRule programmatically using the BasicPolicyRuleEntry implementation.

PolicyRuleEntry myRule = new BasicPolicyRuleEntry
 ("ReportRule", "Report Policy Rule", "Rule for Reports policy.", 
 PolicyRuleEntry.EffectType.GRANT, myCondition);

The values of the parameters are defined as:

• Name - ReportRule is a unique identifier for the policy rule.

• Display Name - Report Policy Rule is an optional, human-readable name for the policy rule.

• Description - Rule for Reports policy is optional information describing the policy rule.

• PolicyRuleEntry.EffectType - takes a value of GRANT based on the desired outcome. The PolicyRuleEntry.EffectType enum defines the available effect types for Oracle Entitlements Server. The constants are GRANT or DENY.

• Condition - myCondition is the name of the optional Condition used by this policy rule. The Condition is a BooleanExpressionEntry which represents an Expression that returns a boolean value. See Section 2.3.5, "Defining a Condition" for more information.

2.2.7 Specifying the Principal

A PrincipalEntry specifies the users, groups, or roles to which the policy pertains. Table 2-5 illustrates these types and how each can be specified programmatically.

PrincipalEntry aUser = new BasicPrincipalEntry
 ("weblogic.security.principal.WLSUserImpl", "smith");
List<PrincipalEntry> myPrincipal = new
 ArrayList<PrincipalEntry>(); myPrincipal.add(aUser);

PrincipalEntry aGroup = new BasicPrincipalEntry
 ("weblogic.security.principal.WLSGroupImpl", "Acme");
List<PrincipalEntry> myPrincipal = new
 ArrayList<PrincipalEntry>(); myPrincipal.add(aGroup);

AppRoleEntry aRole = 
  appRoleManager.getAppRole(tRole);
List<PrincipalEntry> principal = 
  new ArrayList<PrincipalEntry>(); 
principals.add(tRole); 

PrincipalEntry anonymous = new AnonymousRoleEntry();
List<PrincipalEntry> principals = new  
 ArrayList<PrincipalEntry>();
principals.add(anonymous);

PrincipalEntry authenticated = new AuthenticatedRoleEntry();
List<PrincipalEntry> principals = new
 ArrayList<PrincipalEntry>();
principals.add(authenticated);

When a policy's subject is multiple groups and/or roles, that policy applies to a user based on the principal semantic defined. Options include:

• PRINCIPAL_AND_SEMANTIC defines a policy that applies to a user if the user matches ALL groups or roles listed as the principal. For example, if a list of principals contains two roles, the user must be member of both roles for the policy to apply.

• PRINCIPAL_OR_SEMANTIC defines a policy that applies to a user if the user matches AT LEAST one of the groups or roles listed as the principal. For example, if a list of principals contains two roles, the user can be a member of ONLY one of these roles for the policy to apply.

2.2.8 Defining the Policy

A Policy specifies the access rights that specific principals have on specific resources. Basically, it consolidates all the pieces needed to create the access control - including, but not limited to, a PolicyRuleEntry, a ResourceActionsEntry, and a PrincipalEntry.

A Policy is programmatically represented as a PolicyEntry object. To create a PolicyEntry object, obtain an instance of the PolicyManager using the getPolicyManager() method. Following that, use the createPolicy() method to create the object. Example 2-7 creates a policy named myPolicy.

PolicyManager policyMgr = domain.getPolicyManager();
 
List<PermissionSetEntry> permSets = new ArrayList<PermissionSetEntry>();
permSets.add(permSet1);
permSets.add(permSet2);
 
List<PrincipalEntry> principals = new ArrayList<PrincipalEntry>();
principals.add(appRole1);
principals.add(new BasicPrincipalEntry(WLSUserImpl.class.getCanonicalName(), "john"));
 
PolicyEntry myPolicy = policyManager.createPolicy
 ("BankPolicy", "Bank policy", "Policy for bank.", myRule, 
 permSets, principals, null, obligations, PolicyEntry.POLICY_SEMANTIC.AND); 

domain refers to the Policy Domain under which the policy is being created. The values of the createPolicy() parameters are defined as:

• Name - Bank Policy is a unique identifier for the PolicyEntry.

• Display Name - Bank policy is an optional, human-readable name for the PolicyEntry.

• Description - Policy for bank. is optional information describing the PolicyEntry.

• Policy Rule - myrule is the PolicyRuleEntry object.

• PermissionSetEntry - permSets is an ordered collection (list) of PermissionSetEntry objects. See Section 2.3.4, "Defining Permission Sets" for more information.

• Principal - principals is an ordered collection (list) of PrincipalEntry objects defined as the subject of this policy.

• ResourceActionsEntry - A list of ResourceActionsEntry objects can also be defined. If the list of PermissionSetEntry objects is null, this list should contain at least one valid element.

• Obligations - A list of ObligationEntry objects may be used. See Section 2.3.6, "Adding Obligations" for more information.

• policySemantic - describes how principals specified in the policy should be handled. The PolicyEntry.POLICY_SEMANTIC enum defines the available constants as AND or OR.

  • PolicyEntry.POLICY_SEMANTIC.AND applies to a user if the user matches all principals listed in the policy. For example, if a list of principals contains two roles, the user must be a member of both roles for the policy to apply.

  • PolicyEntry.POLICY_SEMANTIC.OR applies to a user if the user matches at least one of the principals listed in the policy. For example, if list of principals contains two roles, the user can be a member of at least one of these roles for the policy to apply.

2.3.1 Creating Application Roles

An AppRoleEntry object is associated with an ApplicationPolicy to group access rights that can then be distributed to users who are granted the role. Once an AppRoleEntry is defined, the grantAppRole method can be used to assign the role to a subject statically or a Role Mapping Policy can be created to assign it to subjects dynamically. (An Authorization Policy is used to define the role's access rights.)

The following can be added as members to an AppRoleEntry:

• Enterprise users from an identity store

• Enterprise roles from an identity store

• Other Application Roles in a policy store

When an Application Role is specified as a principal for a particular policy, all users assigned to the role are governed by that policy. All ApplicationPolicy containers have two implicit Application Roles:

• Anonymous Role — implicitly assigned to all unauthenticated users.

• Authenticated Role — implicitly assigned to all authenticated users.

To create an AppRoleEntry, get an instance of AppRoleManager from within the ApplicationPolicy object where the Application Role will be created and use the createAppRole() method. Example 2-8 shows the creation of an AppRoleEntry named TraderRole.

AppRoleManager roleMgr = bankApplication.getAppRoleManager(); 
AppRoleEntry traderRole = roleMgr.createAppRole("TraderRole", 
 "Trader Role", "Trader role"); 

bankApplication defines the ApplicationPolicy object for which we are retrieving the AppRoleManager. The values of the createAppRole() parameters are defined as:

• Name - TraderRole is a unique identifier for the AppRoleEntry object.

• Display Name - Trader Role is an optional, human-readable name for the AppRoleEntry object.

• Description - Trader Role is optional information describing the AppRoleEntry object.

To assign a Principal to an AppRoleEntry object, build a PrincipalEntry list containing the appropriate users or groups. Use grantAppRole() to assign the role to the principals in the list. Example 2-9 shows the creation and assignment of user JSMITH to the TraderRole.

//create user named JSMITH PrincipalEntry aUser = new
BasicPrincipalEntry("weblogic.security.principal.WLSUserImpl", "JSMITH");

//Add user to principals list
List<PrincipalEntry> principal = new ArrayList<PrincipalEntry>();
principal.add(aUser);

//assign user to role.
roleMgr.grantAppRole(traderRole, principal);

The values of the grantAppRole() parameters are defined as:

• Name - TraderRole is the name of the AppRoleEntry object to which the user is being assigned.

• Principal - principal is the name of the list which contains the user being added.

Application Role hierarchies can be built by assigning Application Roles as members of other Application Roles. A policy that applies to an Application Role also applies to all Application Roles that have been assigned to it as members. Example 2-10 illustrates how the TraderManagers role is assigned as a member of the AllManagers role. Thus, all policies that apply to members of the AllManagers role also apply to all members of the TraderManagers role.

//create AllManagers and TraderManagers roles 
AppRoleEntry allManagers = roleMgr.createAppRole("AllManagers", 
 "AllManagers Role","Role for all managers."); 
AppRoleEntry traderManagers = roleMgr.createAppRole(“TraderManagers", 
 "TraderManagers Role", "Role for Trader managers."); 

//add TraderManagers to a principals list 
List<PrincipalEntry> principal = new ArrayList<PrincipalEntry>(); 
principal.add(traderManagers); 

//add TraderManagers role as principal of AllManagers role 
roleMgr.grantAppRole(allManagers, principal); 

2.3.2 Creating Role Mapping Policies

A Role Mapping Policy is created at the ApplicationPolicy level - the same level at which the Application Role is defined. A RolePolicyEntry object represents a Role Mapping Policy. It provides the methods to define a policy that will determine if a user or group is granted or denied an Application Role.

To create a RolePolicyEntry object, obtain an instance of the RolePolicyManager using the getRolePolicyManager() method in the applicable ApplicationPolicy. Following that, use the createRolePolicy() method to create the object.

//get the RolePolicyManager 
RolePolicyManager roleMapPolicyManager = TellerApp.getRolePolicyManager(); 

List<AppRoleEntry> appRoles = new ArrayList<AppRoleEntry>();
appRoles.add(appRole1);
 
List<PrincipalEntry> principals = new ArrayList<PrincipalEntry>();
principals.add(new BasicPrincipalEntry(WLSUserImpl.class.getCanonicalName(), "john"));
 
PolicyRuleEntry rule = new BasicRuleEntry("rule", "rule for role policy", "rule for role policy", EffectType.GRANT, null);
 
List<ResourceEntry> resources = new ArrayList<ResourceEntry>();
resources.add(resource1);

//create the RolePolicyEntry 
RolePolicyEntry rolepolicy = roleMapPolicyManager.createRolePolicy
 ("TellerRoleMapping", "Teller Role Mapping", "Teller Role Mapping Policy",
  appRoles, principals, rule, resources, null); 

TellerApp is the name of the ApplicationPolicy object from which the RolePolicyManager is being retrieved. The values of the createRolePolicyEntry() parameters are defined as:

• Name - TellerRoleMapping is a unique identifier for the RolePolicyEntry.

• Display Name - Teller Role Mapping is an optional, human-readable name for the RolePolicyEntry.

• Description - Teller Role Mapping Policy is optional information describing the ResourceTypeEntry.

• Application Roles List - appRoles is an ordered collection (list) of all application roles to grant (or deny) on evaluation of the RolePolicyEntry.

• Principals List - principals is a collection (list) of PrincipalEntry objects to map to the Application Roles. This value cannot be an ApplicationRole or an Administration Role, and the list cannot be empty.

  Note:

  Role Mapping Policies use only the OR semantic. See Section 2.2.7, "Specifying the Principal" for more information.

• Policy Rule - rule is the PolicyRuleEntry object that defines a Condition for the Role Mapping Policy. A value is required.

  Note:

  Conditions in Role Mapping Policies provide the same functionality as conditions in Authorization Policies.

• Resource Names - resources is a list of ResourceEntry objects to associate with the Role Mapping Policy. It is an optional parameter for which you can supply null or an empty list. This parameter also allows scoping the Role Mapping Policy to a particular resource(s).

• Resource Name Expressions - This value can contain a list of resource name expressions to associate with the Role Mapping Policy. It is an optional parameter for which you can supply null (as in this example) or an empty list. This parameter also allows scoping the Role Mapping Policy to a particular resource(s).

2.3.3 Creating Attribute and Function Definitions

An attribute or function definition is metadata that describes a specific attribute or function. Among other information, it defines the name of the attribute or function, the type of data the attribute takes, or the function returns, as a value and whether said value is single or multiple. The metadata informs Oracle Entitlements Server how to deal with the particular attribute or function that is being defined.Attribute and function definitions can be used in a Condition or an Obligation. In regards to a Condition, attribute and function definitions can be used to make an optional expression that can be added to a policy to further restrict access to the protected resource. In regards to an Obligation, this optional set of name-value pairs returns additional information, with a policy decision, to the Policy Enforcement Point (PEP). There are two ways to define an Obligation:

• Statically where an attribute with an absolute value is returned.

• Dynamically where an attribute value, or a custom function, is evaluated at runtime and the output is returned.

Attribute and function definitions are managed at the ApplicationPolicy level. Pre-defined definitions can be used (RuleExpressionEntry.BuiltInAttributes and RuleExpressionEntry.BuiltInFunctions) or you can define new ones to suit your requirements using the ExtensionManager. More information can be found in the following sections.

• Section 2.3.3.1, "Creating Attribute Definitions."

• Section 2.3.3.2, "Creating Custom Function Definitions."

//get the ExtensionManager 
ExtensionManager xMgr = bankApplication.getExtensionManager(); 

//create the dynamic attribute 
AttributeEntry<OpssString> attr = xMgr.createAttribute
 ("min_age", "minimum age", "minimum age of subject.", OpssString.class,
  AttributeEntry.AttributeCategory.DYNAMIC, true); 

ApplicationPolicy ap = ps.getApplicationPolicy("MyAppPolicy"); 
ExtensionManager xMgr = ap.getExtensionManager(); 
FunctionEntry func = xMgr.createFunction("myFunc", 
  "Credit Standing Function", "Returns credit standing.",
  "acme.demo.CreditStanding", OpssBoolean.class, params);

2.3.4 Defining Permission Sets

As documented in Section 1.2, "Composing A Simple Policy," a PermissionSetEntry object is used to aggregate one or more ResourceActionsEntry objects. A ResourceActionsEntry object is a pairing of the resource being secured with the action(s) that the policy will allow or deny on it. (See Section 2.2.5, "Associating Actions with the Resource" for more information on ResourceActionsEntry objects.) With the PermissionSetEntry, you can bundle ResourceActionsEntry objects as needed. This is a construct that can be used instead of the standard RBAC role aggregations.

Example 2-14 illustrates how to create a PermissionSetEntry object. It includes the code for creating a ResourceEntry and ResourceActionsEntry. domain is the name of the Policy Domain from which the instance of the PermissionSetManager is retrieved.

//get the PermissionSetManager 
PermissionSetManager psMgr = domain.getPermissionSetManager();

//create a ResourceEntry and ResourceActionsEntry
ResourceManager resMgr = domain.getResourceManager();
ResourceEntry checkingRes = resMgr.createResource("Bob_checking1", 
 "Bob Checking Account", "Checking account.", type, null);
List<String> actions = new ArrayList<String>(); 
 actions.add(“read”); 
 actions.add(“write”); 
List<ResourceActionsEntry> resActsList = new 
 ArrayList<ResourceActionsEntry>();
resActsList.add(new BasicResourceActionsEntry(Checking, <actions>));

//create a PermissionSetEntry
PermissionSetEntry permSet = 
 permSetManager.createPermissionSet("RptsPermSet", "Reports Permission Set", 
 "Permission set for Reports policy.", resActsList);

The values of the createPermissionSet() parameters are defined as:

• Name - RptsPermSet is a unique identifier for the PermissionSetEntry object.

• Display Name - Reports Permission Set is an optional, human-readable name for the PermissionSetEntry object.

• Description - Permission set for Report policy. is optional information describing the PermissionSetEntry object.

• ResourceActionsEntry - resActsList is the ResourceActionsEntry being associated with this PermissionSetEntry object.

2.3.5 Defining a Condition

An optional Condition in a policy rule can be used to set additional requirements on a decision returned in response to a request for access. For example, a Condition can be used to grant access to a resource only on the condition that the request was issued from a specific location or at a specific time. A Condition is written in the form of an expression that resolves to either true or false. If the expression resolves to true, the condition is satisfied and the policy is applicable. If the expression does not resolve to true, the policy is not applicable.

A Condition is defined in a PolicyRuleEntry as discussed in Section 2.2.6, "Specifying a Policy Rule." It is an expression built using attributes or functions that can (optionally) be added to the policy rule to further restrict it. The expression is evaluated using dynamic or resource attribute values, or values returned from component functions.

A Condition must return true or false so the expression can only return true or false; thus, it must be defined in a BooleanExpressionEntry. The BooleanExpressionEntry may:

• Have an unlimited number of ExpressionComponent objects.

  An expression object has a function and one or more arguments of the type ExpressionComponent. The ExpressionComponent interface represents any entity that can appear as part of the expression.

  Note:

  the order in which components are added to an expression must be the same order in which the parameters appear in the input parameter list. For example, if a function needs (OpssString, OpssTime, OpssInteger), the expression must be constructed as:

  ex.addExpressionComponent(<string param>);
  ex.addExpressionComponent(<time param>);
  ex.addExpressionComponent(<integer param>);
  

  The following objects are of the type ExpressionComponent:

  • Any DataType object

    See Section 2.1, "Using the Java API."

  • AttributeEntry

  • ValueCollection

  • Expression

• Nest ExpressionComponent objects.

• Use predefined or custom functions with boolean or non-boolean return types.

• Use predefined or dynamic attributes as function input:

  • A dynamic attribute is one whose value is obtained at evaluation time.

  • A predefined attribute is one whose value is not related to the subject, resource, action of the policy or rule; for example, the time of day.

  • A literal value (defined as an ExpressionComponent) that is of any currently supported data type: Boolean, Date, Integer, String and Time.

• Compare the boolean values returned from two or more expressions using the AND or OR operators.

Example 2-15 illustrates how to define a Condition using the BooleanExpressionEntry class to specify the expression and (optional) parameters.

BooleanExpressionEntry bexp = 
  new BooleanExressionEntry(expression)

The BooleanExpressionEntry parameter has:

• A FunctionEntry for a built-in function, or a custom function obtained using the ExtensionManager.

• Zero or more ExpressionComponent objects. An ExpressionComponent is an interface implemented by Class<? extends DataType>, ValueCollection, AttributeEntry and Expression. The following objects can be used to build an Expression: OpssBoolean, OpssDate, OpssInteger, OpssString, OpssTime, ValueCollection, all classes that implement the AttributeEntry interface, or an Expression itself (nesting). It represents a simple condition such as string1 = string2 or a more complex condition such as (((checking_balance + savings_balance) > 10000) AND (customFunc_checkCustomerType(user_name, “GOLD”)).

From a high level, a developer must take the following steps to define a Condition as a BooleanExpressionEntry. This procedure assumes the logic detailing the process has been defined; in this example, assume a banking policy is applicable only to users who are GOLD members with a combined savings and checking balance of $10,000.

1. Isolate the individual components of the logic for which AttributeEntry objects will be defined; in this example, an attribute that defines a combined savings and checking balance (to compare with $10,000) and one that defines the type of customer (to compare with GOLD).

2. Identify functions implicit in each component for which FunctionEntry objects will be defined; in this example, there is one function that creates a combined balance (saving_balance + checking_balance > 10000) and one that checks for the customer type (customFunc_checkCustomerType(username, “GOLD”)).

3. Build ExpressionComponent objects one by one, identifying them as functions and parameters; in this example, expressions are nested and use the AND operator.

   • integer_add(saving_balance, check_balance)

   • integer_greater_than(integer_add
(saving_balance, check_balance), 10000)

   • customFunc_checkCustomerType(username, “GOLD”)

   • and(integer_greater_than(integer_add
(saving_balance, check_balance), 10000,
customFunc_checkCustomerType(username, “GOLD”))

4. Build the BooleanExpressionEntry using the ExpressionComponent objects. The preferred way to generate a boolean expression is illustrated in Example 2-16.

   Example 2-16 Building a BooleanExpressionEntry

   //Define the checking and savings balances and compute one total
   
   Expression addBalance = new Expression(function entry for integer_add);
   addBalance.add(attribute entry for savings_balance);
   addBalance.add(attribute entry for checking_balance);
    
   //Compare the total balance to 10,000
   
   Expression greaterThan = new Expression
     (function entry for integer_greater_than);
   greaterThan.addExpressionComponent(addBalance);
   greaterThan.addExpressionComponent(new OpssInteger(10000));
    
   //Define the function to check the customer type
   
   Expression goldMember = new Expression(function entry for customFunc_checkCustomerType);
   goldMember.addExpressionComponent(attribute entry for username);
   goldMember.addExpressionComponent(new OpssString(“GOLD”));
    
   //Compare the outcome using AND operator
   
   Expression top = new Expression(function entry for AND);
   top.addExpressionComponent(greaterThan);
   top.addExpressionComponent(goldMember);
   

   The expression constructor is provided with the function entry, and each function argument is added as an expression component from left to right.

   Note:

   To add all ExpressionComponent objects at once, use the setExpressionComponent(List<ExpressionComponent>) interface. The list of components must be built in order of the arguments passed to the function; for example, the first component in the list is the first argument passed to the function, the second component is the second argument and so on.

5. Create a BooleanExpressionEntry.

Oracle Entitlements Server supports many predefined functions to be used in conditions (AND/OR, boolean functions, or string functions). The following sections contain information on the kinds of expressions that can be used.

• Section 2.3.5.1, "Constructing a Boolean Expression"

• Section 2.3.5.2, "Constructing a Custom Function Expression"

Expression leftExpression = 
  new Expression(function-entry-for-INTEGER_LESS_THAN);
leftExpression.add(attribute entry for userBudget);
leftExpression.add(new OpssInteger(2000));

Expression rightExpression = 
  new Expression(function-entry-for-STRING_EQUAL);
rightExpression.addExpressionComponent(thisMonth);
rightExpression.addExpressionComponent(new OpssString("December"));

Expression expression = new Expression(function-entry-for-AND);
expression.addExpressionComponent(leftExpression);
expression.addExpressionComponent(rightExpression);

//boolean expression 
RuleExpressionEntry<OpssBoolean> condition =  
  new BooleanExpressionEntry<OpssBoolean>(expression);

//get the ClientType custom function 
FunctionEntry function = xMgr.getFunction("ClientType");
Expression ex = new Expression(function);

//add component referencing "LowRisk" string to expression
ex.addExpressionComponent(new OpssString("LowRisk");

//construct BooleanExpressionEntry to invoke function 
RuleExpressionEntry<OpssBoolean> = new BooleanExpressionEntry(ex);

// define the acceptable expression value types 
List<Class<? extends DataType>> inputParams = 
 new ArrayList<Class <? extends DataType>>(); 
  inputParams.add(OpssInteger.class); 
  inputParams.add(OpssString.class); 
  inputParams.add(OpssTime.class 
); 

// declare the function 
FunctionEntry func = extensionManager.createFunction(“ReportsPolicyCondition”, 
“ReportsPolicyCondition”, “Condition for Reports policy.”, 
“oracle.demo.oes.ComplexFunction”, OpssBoolean.class, inputParams); 

// use the function to construct a condition 
AttributeEntry<OpssInteger> attrEntry = 
 extMngr.getAttribute(BuiltInAttributes.SYS_OBJ.toString()); 

Expression expression = new Expression (func)

expression.addExpressionComponent(new OpssInteger(100));
expression.addExpressionComponent(attrEntry);
expression.addExpressionComponent(new OpssTime(17, 0, 0));

RuleExpressionEntry<OpssBoolean> condition = 
  new BooleanExpressionEntry <OpssBoolean>(expression);

2.3.6 Adding Obligations

An Obligation specifies optional information that is taken into account during policy enforcement. This information is returned to the entity calling for an authorization decision with the resolved effect (GRANT or DENY) and imposes an additional requirement on the policy outcome; for example, if a certain amount of money is withdrawn from a checking account, send a text message to the account holder's registered mobile phone.

An Obligation is managed as a named object that contains a set of name-value pairs. The object is always managed in the context of a policy. There are two ways to define an Obligation:

• Statically where an attribute with an absolute value is returned as an Obligation.

• Dynamically where an attribute value, or a custom function, is evaluated at runtime and the output is returned as the Obligation.

If a policy contains an Obligation, the information is returned to the application as a named ObligationEntry object containing a set of attributes. To specify an Obligation, build an ObligationEntry object that contains the data to return. The following procedure constructs an ObligationEntry that provides the string message Trader managers may run reports.

1. Define the message string using the AttributeAssignment class and add it to an attribute array list named traderRptList.

   AttributeAssignment<OpssString>traderRpts = new 
    AttributeAssignment<OpssString>
    ("traderRptMessage", new OpssString("Trader managers may run reports.")); 
   List<AttributeAssignment<? extends DataType>> traderRptList = 
    new ArrayList<AttributeAssignment<? extends DataType>>(); 
   traderRptList.add(traderRpt); 
   

   The values of the parameters are defined as:

   • Name - traderRptMessage is a unique identifier for the string.

   • OpssString - Trader managers may run reports. is the string.

2. Construct the traderRptObl Obligation and traderRptOblList array using the ObligationEntry interface.

   ObligationEntry traderRptObl = new BasicObligationEntry
    ("traderRptObl", "Trader Report Obligation", 
     "obligation for Trader Report policy.", traderRptList); 
   List<ObligationEntry>traderRptOblList = new ArrayList<ObligationEntry>(); 
   traderRptOblList.add(traderRptObl);
   

   The values of the parameters are defined as:

   • Name - traderRptObl is a unique identifier for the Obligation.

   • Display Name - Trader Report Obligation is an optional, human-readable name for the Obligation.

   • Description - Obligation for Trader Report policy. is an optional description of the Obligation.

   • Assignments - traderRptList is the attribute array list previously created.

3. Specify the obligation when creating the policy.

   PolicyEntry policyEntry = policyManager.createPolicy
    ("TraderRpt", "TraderRpt", "Trader report policy.", traderRptRule, 
     traderRptPermissionSetEntryList, traderRptPrincipals, traderRptOblList); 
   

   The values of the parameters are defined as:

   • Name - TraderRpt is a unique identifier for the policy.

   • Display Name - TraderRpt is an optional, human-readable name for the policy.

   • Description - Trader Report policy. is an optional description.

   • Rule - traderRptRule is the name of the PolicyRuleEntry object.

   • PermSets - traderRpt is a list of PermissionSetEntry objects.

   • Principals - traderRptPrincipals is a list of PrincipalEntry objects.

   • Obligations - traderRptRule is a list of ObligationEntry objects.